Swiftui Design Principles

作者 arjitj2791d22d73f844167a3872530e3941185b730d8beMIT30 个星标收录于 2026年10月9日更新于 2026年10月9日仓库6个月前更新

Design principles for building polished, native-feeling SwiftUI apps and widgets. Use this skill when creating or modifying SwiftUI views, iOS widgets (WidgetKit), or any native Apple UI. Ensures proper spacing, typography, colors, and widget implementations that look and feel like quality apps rather than AI-generated slop.

仅含说明Design & Creative Software Development

AI 生成的概览

用于打造精致、原生感 SwiftUI 应用与 WidgetKit 界面的设计原则指南。

功能: 该技能提供一套 SwiftUI 与 WidgetKit 界面设计原则，涵盖间距网格、字体层级、语义颜色、组件尺寸、分组卡片、导航、小组件、交互元素以及编辑器状态管理。它通过带注释的代码示例对比应避免与推荐的做法，并以发布前检查清单收尾。产出的是书面指导，而非生成文件或代码产物。
适用场景: 在创建或修改 SwiftUI 视图、iOS 小组件、锁屏小组件或其他原生 Apple UI 时使用。它旨在让间距、字体、颜色和小组件实现保持与高质量应用一致。
运行要求: 无需脚本或工具，仅为说明性文档。需要熟悉 SwiftUI 与 WidgetKit API。

This skill encodes design principles derived from comparing polished, production-quality SwiftUI apps against poorly-built ones. The patterns here represent what separates an app that feels "right" from one where the margins, spacing, and text sizes just look "off."

Apply these principles whenever building or modifying SwiftUI interfaces, WidgetKit widgets, or any native Apple UI.

Core Philosophy

Restraint over decoration. Every pixel must earn its place. A polished app uses fewer colors, fewer font sizes, fewer spacing values, and fewer words — but uses them consistently. Over-engineering visual elements (custom gradients, decorative borders, bespoke dividers) creates visual noise. Native components and system colors create harmony.

Attention is scarce. Keep UI copy shorter than you think it needs to be. Prefer one clear headline and one compact supporting block over repeated explanation in the title, subtitle, body, and footer. If a screen needs rationale, put it in one purposeful place instead of scattering it across the page.

1. Spacing System: Use a Consistent Grid

CRITICAL: Use spacing values from a base-4/base-8 grid. Never use arbitrary values.

Allowed spacing values

Bad (arbitrary values that create visual dissonance)

swift

// WRONG - these numbers have no relationship to each other.padding(.bottom, 26).padding(.bottom, 34).padding(.bottom, 36)HStack(spacing: 18).padding(14)

// WRONG - these numbers have no relationship to each other.padding(.bottom, 26).padding(.bottom, 34).padding(.bottom, 36)HStack(spacing: 18).padding(14)

Good (values from a consistent grid)

swift

// RIGHT - predictable rhythm the eye can follow.padding(.horizontal, 20).padding(.top, 8)Spacer().frame(height: 32)HStack(spacing: 4)  // or 8, 12, 16.padding(.vertical, 12).padding(.horizontal, 16)

// RIGHT - predictable rhythm the eye can follow.padding(.horizontal, 20).padding(.top, 8)Spacer().frame(height: 32)HStack(spacing: 4)  // or 8, 12, 16.padding(.vertical, 12).padding(.horizontal, 16)

Standard padding assignments

Outer content padding: 16-20pt horizontal
Between major sections: 24-32pt vertical
Within grouped components: 4-12pt
Card/row internal padding: 12-16pt vertical, 16pt horizontal

2. Typography: Hierarchy Through Weight, Not Just Size

The principle

Use fewer font sizes with clear weight differentiation. Lighter weights at larger sizes; medium/regular at smaller sizes. This creates sophistication rather than visual chaos.

Recommended type scale (for a data-focused app)

Role	Size	Weight	Notes
Hero number	36-42pt	`.light`	Large but visually light -- elegant, not heavy
Secondary stat	20-24pt	`.light`	Same weight family as hero, smaller
Body / toggle label	15pt	`.regular`	Standard iOS body size
Section header (uppercase)	11pt	`.medium`	With tracking/letter-spacing
Caption / subtitle	11-13pt	`.regular`	Secondary information

Bad (too many sizes, inconsistent weights)

swift

// WRONG - 7 different sizes with no clear system.font(.system(size: 60, weight: .ultraLight))   // hero.font(.system(size: 44, weight: .regular))        // stat (too close to hero).font(.system(size: 31, weight: .ultraLight))     // percent symbol (odd ratio).font(.system(size: 18, weight: .regular))        // label (too big for a toggle).font(.system(size: 14, weight: .regular))        // header.font(.system(size: 13, weight: .regular))        // another header.font(.system(size: 12, weight: .regular))        // button (too small to read)

// WRONG - 7 different sizes with no clear system.font(.system(size: 60, weight: .ultraLight))   // hero.font(.system(size: 44, weight: .regular))        // stat (too close to hero).font(.system(size: 31, weight: .ultraLight))     // percent symbol (odd ratio).font(.system(size: 18, weight: .regular))        // label (too big for a toggle).font(.system(size: 14, weight: .regular))        // header.font(.system(size: 13, weight: .regular))        // another header.font(.system(size: 12, weight: .regular))        // button (too small to read)

Good (clear hierarchy, fewer sizes)

swift

// RIGHT - 5 sizes, clear purpose for each.font(.system(size: 42, weight: .light, design: .monospaced))    // hero.font(.system(size: 24, weight: .light, design: .monospaced))    // stat value.font(.system(size: 15, weight: .regular, design: .monospaced))  // body.font(.system(size: 14, weight: .regular, design: .monospaced))  // secondary.font(.system(size: 11, weight: .medium, design: .monospaced))   // label

// RIGHT - 5 sizes, clear purpose for each.font(.system(size: 42, weight: .light, design: .monospaced))    // hero.font(.system(size: 24, weight: .light, design: .monospaced))    // stat value.font(.system(size: 15, weight: .regular, design: .monospaced))  // body.font(.system(size: 14, weight: .regular, design: .monospaced))  // secondary.font(.system(size: 11, weight: .medium, design: .monospaced))   // label

Font design consistency

Pick ONE font design and use it everywhere -- app AND widgets:

swift

// If using monospaced, use it everywheredesign: .monospaced  // app views, widgets, lock screen -- all of them
// NEVER mix designs between app and widgets// BAD: .monospaced in app, .rounded in lock screen widget

// If using monospaced, use it everywheredesign: .monospaced  // app views, widgets, lock screen -- all of them
// NEVER mix designs between app and widgets// BAD: .monospaced in app, .rounded in lock screen widget

Letter spacing (tracking)

Use at most 2 values, and only on uppercase labels:

swift

.tracking(1.5)  // section labels: "NOTIFICATIONS", "DAY", "LEFT".tracking(3)    // navigation/toolbar titles

.tracking(1.5)  // section labels: "NOTIFICATIONS", "DAY", "LEFT".tracking(3)    // navigation/toolbar titles

Never use 3+ different tracking values like kerning(4), kerning(4.5), kerning(5) -- the differences are imperceptible but the inconsistency registers subconsciously.

Numeric formatting for identifiers

Years and other fixed identifiers should not be locale-grouped.

swift

// RIGHT - stable, non-grouped identifier textText(String(year))                  // "2026"Text(year, format: .number.grouping(.never))
// WRONG - locale grouping can render "2,026"Text("\(year)")

// RIGHT - stable, non-grouped identifier textText(String(year))                  // "2026"Text(year, format: .number.grouping(.never))
// WRONG - locale grouping can render "2,026"Text("\(year)")

3. Colors: System Semantic Colors Over Hardcoded Values

The principle

Use SwiftUI's semantic color system. It automatically handles light/dark mode, accessibility, and looks native. Hardcoded colors with manual opacity values create maintenance nightmares and look artificial.

Bad (hardcoded white with a dozen opacity values)

swift

// WRONG - impossible to maintain, doesn't adapt to light modeColor.black.ignoresSafeArea()           // forced darkColor.white.opacity(0.08)               // ring backgroundColor.white.opacity(0.09)               // dividerColor.white.opacity(0.3)                // year textColor.white.opacity(0.32)               // stat labelColor.white.opacity(0.42)               // percent symbolColor.white.opacity(0.44)               // toggle tintColor.white.opacity(0.72)               // button textColor.white.opacity(0.88)               // toggle labelColor.white.opacity(0.9)                // stat valueColor.white.opacity(0.94)               // ring fill

// WRONG - impossible to maintain, doesn't adapt to light modeColor.black.ignoresSafeArea()           // forced darkColor.white.opacity(0.08)               // ring backgroundColor.white.opacity(0.09)               // dividerColor.white.opacity(0.3)                // year textColor.white.opacity(0.32)               // stat labelColor.white.opacity(0.42)               // percent symbolColor.white.opacity(0.44)               // toggle tintColor.white.opacity(0.72)               // button textColor.white.opacity(0.88)               // toggle labelColor.white.opacity(0.9)                // stat valueColor.white.opacity(0.94)               // ring fill

Good (semantic system colors)

swift

// RIGHT - adapts automatically, looks native, easy to maintainColor(.systemBackground)                 // main backgroundColor(.secondarySystemBackground)        // card/group backgroundsColor(.separator)                        // dividers (with optional opacity)Color.primary                            // primary text and UI elements.foregroundStyle(.secondary)              // secondary text.foregroundStyle(.tertiary)               // labels, captions

// RIGHT - adapts automatically, looks native, easy to maintainColor(.systemBackground)                 // main backgroundColor(.secondarySystemBackground)        // card/group backgroundsColor(.separator)                        // dividers (with optional opacity)Color.primary                            // primary text and UI elements.foregroundStyle(.secondary)              // secondary text.foregroundStyle(.tertiary)               // labels, captions

When you do need opacity

Limit to 2-3 values with clear purposes:

swift

.opacity(0.15)  // subtle background strokes.opacity(0.3)   // separator lines// That's it. If you need more, you're probably hardcoding what semantic colors handle.

.opacity(0.15)  // subtle background strokes.opacity(0.3)   // separator lines// That's it. If you need more, you're probably hardcoding what semantic colors handle.

4. Component Sizing: Proportional, Not Oversized

Progress rings / circular indicators

swift

// App main view: 200x200 with thin stroke.frame(width: 200, height: 200)Circle().stroke(..., lineWidth: 3)
// Widget (systemSmall): 90x90, same stroke.frame(width: 90, height: 90)Circle().stroke(..., lineWidth: 3)
// WRONG: oversized ring with thick inconsistent strokes.frame(width: 260, height: 260)    // too large, dominates screenCircle().stroke(..., lineWidth: 9)  // backgroundCircle().stroke(..., lineWidth: 8)  // fill -- WHY different from background?

// App main view: 200x200 with thin stroke.frame(width: 200, height: 200)Circle().stroke(..., lineWidth: 3)
// Widget (systemSmall): 90x90, same stroke.frame(width: 90, height: 90)Circle().stroke(..., lineWidth: 3)
// WRONG: oversized ring with thick inconsistent strokes.frame(width: 260, height: 260)    // too large, dominates screenCircle().stroke(..., lineWidth: 9)  // backgroundCircle().stroke(..., lineWidth: 8)  // fill -- WHY different from background?

Stroke width consistency

Always use the same lineWidth for background and foreground strokes of the same element:

swift

// RIGHTCircle().stroke(background, lineWidth: 3)Circle().trim(from: 0, to: fraction).stroke(fill, lineWidth: 3)
// WRONG - creates visual misalignmentCircle().stroke(background, lineWidth: 9)Circle().trim(from: 0, to: fraction).stroke(fill, lineWidth: 8)

// RIGHTCircle().stroke(background, lineWidth: 3)Circle().trim(from: 0, to: fraction).stroke(fill, lineWidth: 3)
// WRONG - creates visual misalignmentCircle().stroke(background, lineWidth: 9)Circle().trim(from: 0, to: fraction).stroke(fill, lineWidth: 8)

List rows and toggle rows

swift

// RIGHT - natural sizing with proper paddingToggle(isOn: $value) {    Text(title)        .font(.system(size: 15, weight: .regular, design: .monospaced))}.padding(.horizontal, 16).padding(.vertical, 12)
// WRONG - fixed oversized heightHStack {    Text(label)        .font(.system(size: 18))   // too big for a toggle label    Spacer()    Toggle("", isOn: $isOn)        .labelsHidden()             // why hide the label? Use Toggle properly}.frame(height: 70)                  // way too tall

// RIGHT - natural sizing with proper paddingToggle(isOn: $value) {    Text(title)        .font(.system(size: 15, weight: .regular, design: .monospaced))}.padding(.horizontal, 16).padding(.vertical, 12)
// WRONG - fixed oversized heightHStack {    Text(label)        .font(.system(size: 18))   // too big for a toggle label    Spacer()    Toggle("", isOn: $isOn)        .labelsHidden()             // why hide the label? Use Toggle properly}.frame(height: 70)                  // way too tall

5. Grouped Content & Cards: Use System Patterns

Bad (over-engineered custom card)

swift

// WRONG - custom gradient, overlay border, huge corner radiusVStack { ... }    .padding(.vertical, 4)              // too tight    .background(        RoundedRectangle(cornerRadius: 22)   // too round            .fill(LinearGradient(            // unnecessary gradient                colors: [Color(white: 0.10), Color(white: 0.085)],                startPoint: .topLeading, endPoint: .bottomTrailing            ))    )    .overlay(        RoundedRectangle(cornerRadius: 22)            .stroke(Color.white.opacity(0.08), lineWidth: 1)  // decorative border    )

// WRONG - custom gradient, overlay border, huge corner radiusVStack { ... }    .padding(.vertical, 4)              // too tight    .background(        RoundedRectangle(cornerRadius: 22)   // too round            .fill(LinearGradient(            // unnecessary gradient                colors: [Color(white: 0.10), Color(white: 0.085)],                startPoint: .topLeading, endPoint: .bottomTrailing            ))    )    .overlay(        RoundedRectangle(cornerRadius: 22)            .stroke(Color.white.opacity(0.08), lineWidth: 1)  // decorative border    )

Good (native grouped style)

swift

// RIGHT - simple, native, works in light and dark modeVStack(spacing: 0) {    row1    Divider().padding(.leading, 16)    row2    Divider().padding(.leading, 16)    row3}.background(Color(.secondarySystemBackground)).clipShape(.rect(cornerRadius: 10))

// RIGHT - simple, native, works in light and dark modeVStack(spacing: 0) {    row1    Divider().padding(.leading, 16)    row2    Divider().padding(.leading, 16)    row3}.background(Color(.secondarySystemBackground)).clipShape(.rect(cornerRadius: 10))

Key rules for grouped content

Corner radius: 10pt for cards/groups (matches iOS system style). Never 22pt+.
Dividers: Use the system Divider() with .padding(.leading, 16) for iOS-standard inset. Never build custom divider structs.
Card padding: 12-16pt vertical, 16pt horizontal. Never 4pt vertical.
Background: Color(.secondarySystemBackground) -- never custom gradients for standard cards.

6. Navigation: Use NavigationStack

swift

// RIGHT - proper navigation with minimal toolbarNavigationStack {    ScrollView {        content    }    .toolbar {        ToolbarItem(placement: .principal) {            Text("Title")                .font(.system(size: 13, weight: .medium, design: .monospaced))                .tracking(3)                .foregroundStyle(.tertiary)        }    }    .navigationBarTitleDisplayMode(.inline)}
// WRONG - no navigation structure, just a ZStackZStack {    Color.black.ignoresSafeArea()    ScrollView {        VStack {            Text("2026").font(...) // manually placed "title"            content        }    }}

// RIGHT - proper navigation with minimal toolbarNavigationStack {    ScrollView {        content    }    .toolbar {        ToolbarItem(placement: .principal) {            Text("Title")                .font(.system(size: 13, weight: .medium, design: .monospaced))                .tracking(3)                .foregroundStyle(.tertiary)        }    }    .navigationBarTitleDisplayMode(.inline)}
// WRONG - no navigation structure, just a ZStackZStack {    Color.black.ignoresSafeArea()    ScrollView {        VStack {            Text("2026").font(...) // manually placed "title"            content        }    }}

7. WidgetKit: Use Native Components

Circular lock screen widget

swift

// RIGHT - use Gauge, it's purpose-built for thisGauge(value: entry.fraction) {    Text("")} currentValueLabel: {    Text("\(Int(entry.percentage))%")        .font(.system(size: 12, weight: .medium, design: .monospaced))}.gaugeStyle(.accessoryCircular).containerBackground(.fill.tertiary, for: .widget)
// WRONG - manual circle drawing for lock screenZStack {    Circle().stroke(Color.primary.opacity(0.18), lineWidth: 4)    Circle().trim(from: 0, to: progress).stroke(...)    Text(percentText)        .font(.system(size: 14, weight: .bold, design: .rounded)) // wrong font design!}

// RIGHT - use Gauge, it's purpose-built for thisGauge(value: entry.fraction) {    Text("")} currentValueLabel: {    Text("\(Int(entry.percentage))%")        .font(.system(size: 12, weight: .medium, design: .monospaced))}.gaugeStyle(.accessoryCircular).containerBackground(.fill.tertiary, for: .widget)
// WRONG - manual circle drawing for lock screenZStack {    Circle().stroke(Color.primary.opacity(0.18), lineWidth: 4)    Circle().trim(from: 0, to: progress).stroke(...)    Text(percentText)        .font(.system(size: 14, weight: .bold, design: .rounded)) // wrong font design!}

Rectangular lock screen widget

swift

// RIGHT - use Gauge with linearCapacityVStack(alignment: .leading, spacing: 4) {    HStack {        Text(year).font(.system(size: 13, weight: .semibold, design: .monospaced))        Spacer()        Text(percentage).font(.system(size: 13, weight: .medium, design: .monospaced))            .foregroundStyle(.secondary)    }    Gauge(value: fraction) { Text("") }        .gaugeStyle(.linearCapacity)        .tint(.primary)    HStack {        Spacer()        Text("\(dayOfYear)/\(totalDays)")            .font(.system(size: 11, weight: .regular, design: .monospaced))            .foregroundStyle(.secondary)    }}.containerBackground(.fill.tertiary, for: .widget)
// WRONG - custom GeometryReader progress barGeometryReader { proxy in    ZStack(alignment: .leading) {        RoundedRectangle(cornerRadius: 2).fill(Color.primary.opacity(0.16))        RoundedRectangle(cornerRadius: 2).fill(Color.primary)            .frame(width: max(2, proxy.size.width * progress))    }}.frame(height: 6)

// RIGHT - use Gauge with linearCapacityVStack(alignment: .leading, spacing: 4) {    HStack {        Text(year).font(.system(size: 13, weight: .semibold, design: .monospaced))        Spacer()        Text(percentage).font(.system(size: 13, weight: .medium, design: .monospaced))            .foregroundStyle(.secondary)    }    Gauge(value: fraction) { Text("") }        .gaugeStyle(.linearCapacity)        .tint(.primary)    HStack {        Spacer()        Text("\(dayOfYear)/\(totalDays)")            .font(.system(size: 11, weight: .regular, design: .monospaced))            .foregroundStyle(.secondary)    }}.containerBackground(.fill.tertiary, for: .widget)
// WRONG - custom GeometryReader progress barGeometryReader { proxy in    ZStack(alignment: .leading) {        RoundedRectangle(cornerRadius: 2).fill(Color.primary.opacity(0.16))        RoundedRectangle(cornerRadius: 2).fill(Color.primary)            .frame(width: max(2, proxy.size.width * progress))    }}.frame(height: 6)

Widget background

swift

// RIGHT.containerBackground(.fill.tertiary, for: .widget)
// WRONG - hardcoded color.containerBackground(.black, for: .widget)

// RIGHT.containerBackground(.fill.tertiary, for: .widget)
// WRONG - hardcoded color.containerBackground(.black, for: .widget)

Widget family coverage

Support all relevant families -- don't skip common ones:

swift

.supportedFamilies([    .accessoryCircular,      // lock screen circle    .accessoryRectangular,   // lock screen rectangle    .accessoryInline,        // lock screen inline text    .systemSmall,            // home screen small    .systemMedium,           // home screen medium    .systemLarge,            // home screen large])

.supportedFamilies([    .accessoryCircular,      // lock screen circle    .accessoryRectangular,   // lock screen rectangle    .accessoryInline,        // lock screen inline text    .systemSmall,            // home screen small    .systemMedium,           // home screen medium    .systemLarge,            // home screen large])

Cross-family visual consistency

Medium and large home widgets should share the same structural layout:

Header: year on the left, percentage on the right
Middle: progress bar
Footer: day/total right aligned

Do not re-invent hierarchy per family unless there is a hard size constraint.

Always include explicit internal padding on home widgets to avoid clipping near rounded edges:

Widget memory budget (hard limit)

Widget extensions have a tight memory budget (commonly around 30 MB). Dense visualizations can be killed by EXC_RESOURCE if built from too many nested views.

swift

// RIGHT - draw dense dot grids in one passCanvas { context, size in    // draw 365/366 dots here}
// WRONG - hundreds of nested subviews (high memory overhead)LazyVGrid(columns: columns) {    ForEach(1...366, id: \.self) { day in        ZStack { Circle(); partialFillLayer }    }}

// RIGHT - draw dense dot grids in one passCanvas { context, size in    // draw 365/366 dots here}
// WRONG - hundreds of nested subviews (high memory overhead)LazyVGrid(columns: columns) {    ForEach(1...366, id: \.self) { day in        ZStack { Circle(); partialFillLayer }    }}

Timeline refresh (match data granularity)

swift

// RIGHT - refresh at midnight for day-level datalet tomorrow = calendar.startOfDay(for: calendar.date(byAdding: .day, value: 1, to: now)!)Timeline(entries: [entry], policy: .after(tomorrow))
// RIGHT - periodic refresh for time-of-day dependent percentages/partial fillslet refresh = Calendar.current.date(byAdding: .minute, value: 15, to: now)!Timeline(entries: [entry], policy: .after(refresh))
// WRONG - minute-level refresh for static daily datalet tooFrequent = Calendar.current.date(byAdding: .minute, value: 1, to: now)!Timeline(entries: [entry], policy: .after(tooFrequent))

// RIGHT - refresh at midnight for day-level datalet tomorrow = calendar.startOfDay(for: calendar.date(byAdding: .day, value: 1, to: now)!)Timeline(entries: [entry], policy: .after(tomorrow))
// RIGHT - periodic refresh for time-of-day dependent percentages/partial fillslet refresh = Calendar.current.date(byAdding: .minute, value: 15, to: now)!Timeline(entries: [entry], policy: .after(refresh))
// WRONG - minute-level refresh for static daily datalet tooFrequent = Calendar.current.date(byAdding: .minute, value: 1, to: now)!Timeline(entries: [entry], policy: .after(tooFrequent))

8. Interactive Elements

Toggles

swift

// RIGHT - use Toggle with its built-in label, tint with a single accent colorToggle(isOn: $value) {    Text(title)        .font(.system(size: 15, weight: .regular, design: .monospaced))}.tint(.green)
// WRONG - hidden label with manual HStack layoutHStack {    Text(label).font(.system(size: 18))    Spacer()    Toggle("", isOn: $isOn)        .labelsHidden()        .tint(Color.white.opacity(0.44))  // low-contrast tint}

// RIGHT - use Toggle with its built-in label, tint with a single accent colorToggle(isOn: $value) {    Text(title)        .font(.system(size: 15, weight: .regular, design: .monospaced))}.tint(.green)
// WRONG - hidden label with manual HStack layoutHStack {    Text(label).font(.system(size: 18))    Spacer()    Toggle("", isOn: $isOn)        .labelsHidden()        .tint(Color.white.opacity(0.44))  // low-contrast tint}

Mutually exclusive options

When options are exclusive (e.g. daily/weekly/monthly cadence), use one selected value, not three independent toggles.

swift

// RIGHT - single source of truthenum Cadence: String, CaseIterable { case daily, weekly, monthly }@State private var cadence: Cadence = .daily
ForEach(Cadence.allCases, id: \.rawValue) { option in    Button {        cadence = option    } label: {        HStack {            Image(systemName: cadence == option ? "checkmark.circle.fill" : "circle")            Text(option.rawValue.capitalized)        }    }}
// RIGHT - one preview action when content is sharedButton("Preview") { sendPreview() }
// WRONG - independent toggles allow contradictory stateToggle("Daily", isOn: $daily)Toggle("Weekly", isOn: $weekly)Toggle("Monthly", isOn: $monthly)

// RIGHT - single source of truthenum Cadence: String, CaseIterable { case daily, weekly, monthly }@State private var cadence: Cadence = .daily
ForEach(Cadence.allCases, id: \.rawValue) { option in    Button {        cadence = option    } label: {        HStack {            Image(systemName: cadence == option ? "checkmark.circle.fill" : "circle")            Text(option.rawValue.capitalized)        }    }}
// RIGHT - one preview action when content is sharedButton("Preview") { sendPreview() }
// WRONG - independent toggles allow contradictory stateToggle("Daily", isOn: $daily)Toggle("Weekly", isOn: $weekly)Toggle("Monthly", isOn: $monthly)

Animated transitions for changing numbers

swift

// Add to any Text that displays a changing numeric valueText(String(format: "%.2f", percentage))    .contentTransition(.numericText())

// Add to any Text that displays a changing numeric valueText(String(format: "%.2f", percentage))    .contentTransition(.numericText())

9. Interactive Editors: Centralize Geometry and State

Interactive editors (collages, crops, canvases, media framing tools, layout pickers) need stricter state and layout discipline than ordinary forms.

Presentation state

Present editor flows from payload state, not from a separate Bool plus independently-managed data.

swift

// RIGHT - presentation only happens when payload exists@State private var activeCropRequest: CropRequest?
.sheet(item: $activeCropRequest) { request in    CropEditor(request: request)}
// WRONG - the sheet can open before the backing data is ready@State private var showCropEditor = false@State private var selectedImage: UIImage?
.sheet(isPresented: $showCropEditor) {    if let selectedImage { CropEditor(image: selectedImage) }}

// RIGHT - presentation only happens when payload exists@State private var activeCropRequest: CropRequest?
.sheet(item: $activeCropRequest) { request in    CropEditor(request: request)}
// WRONG - the sheet can open before the backing data is ready@State private var showCropEditor = false@State private var selectedImage: UIImage?
.sheet(isPresented: $showCropEditor) {    if let selectedImage { CropEditor(image: selectedImage) }}

Shared geometry model

If the app previews pan/zoom/crop/layout live and later exports the result, use one shared geometry model for both preview and render.

swift

// RIGHT - one source of truth for bounds and transformslet normalized = EditorGeometry.normalizedAdjustment(adjustment, imageSize: image.size, slotSize: slotSize)let drawRect = EditorGeometry.drawRect(for: image.size, in: slotRect, adjustment: adjustment)
// WRONG - preview and export each invent their own mathlet previewOffset = ...let exportOffset = ...

// RIGHT - one source of truth for bounds and transformslet normalized = EditorGeometry.normalizedAdjustment(adjustment, imageSize: image.size, slotSize: slotSize)let drawRect = EditorGeometry.drawRect(for: image.size, in: slotRect, adjustment: adjustment)
// WRONG - preview and export each invent their own mathlet previewOffset = ...let exportOffset = ...

If a user can zoom out enough to reveal background, that must be an intentional part of the shared geometry model, not an editor-only exception.

Gesture coordination

Tap, long-press-drag, and pinch are not independent features. In SwiftUI they compete unless you model their relationship explicitly.

Use a single interaction state for the active tile/card/canvas item.
Decide which gesture has priority and which ones should run simultaneously.
Reset temporary gesture state deliberately when selection changes.
Prefer one coherent state machine over scattered booleans tied to individual gestures.

Fixed editor layout

If the screen must not scroll, budget vertical space top-down using a few named regions:

header
canvas stage
settings region
bottom toolbar

Keep that sizing math in one place. Don't let each subview invent its own height.

Custom headers and safe areas

If you replace the system navigation bar with a custom header:

Be explicit about whether the parent already respects the safe area.
Do not add safeAreaInsets.top reflexively; double-counting it creates obvious dead space.
Keep custom headers compact. They should feel like navigation chrome, not a full content section.

Settings surfaces

When an editor has several configuration modes (Layout, Border, Ratio, Background, etc.), show one active settings surface at a time instead of stacking every control on screen.

This keeps the canvas visually dominant and makes each control group easier to understand.

10. Data Model: Share Between App and Widgets

swift

// RIGHT - one model used everywherestruct YearProgress {    // shared calculation logic    static func current() -> YearProgress { ... }}// Used by both ContentView and widget TimelineProvider
// If percentage is shown as live progress, include time-of-day in shared mathlet dayProgress = elapsedInCurrentDay / totalSecondsInDaylet elapsedDays = Double(dayOfYear - 1) + dayProgresslet fraction = elapsedDays / Double(totalDays)
// WRONG - separate snapshot structs with duplicated date mathstruct YearProgressSnapshot { ... }            // in appstruct YearProgressWidgetSnapshot { ... }      // in widget extension (duplicated!)

// RIGHT - one model used everywherestruct YearProgress {    // shared calculation logic    static func current() -> YearProgress { ... }}// Used by both ContentView and widget TimelineProvider
// If percentage is shown as live progress, include time-of-day in shared mathlet dayProgress = elapsedInCurrentDay / totalSecondsInDaylet elapsedDays = Double(dayOfYear - 1) + dayProgresslet fraction = elapsedDays / Double(totalDays)
// WRONG - separate snapshot structs with duplicated date mathstruct YearProgressSnapshot { ... }            // in appstruct YearProgressWidgetSnapshot { ... }      // in widget extension (duplicated!)

11. Quick Checklist

Before shipping any SwiftUI view, verify:

来源与署名

来源：arjitj2/swiftui-design-principles提交791d22d

许可证： MIT

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

Swiftui Design Principles

Core Philosophy

1. Spacing System: Use a Consistent Grid

Allowed spacing values

Bad (arbitrary values that create visual dissonance)

Good (values from a consistent grid)

Standard padding assignments

2. Typography: Hierarchy Through Weight, Not Just Size

The principle

Recommended type scale (for a data-focused app)

Bad (too many sizes, inconsistent weights)

Good (clear hierarchy, fewer sizes)

Font design consistency

Letter spacing (tracking)

Numeric formatting for identifiers

3. Colors: System Semantic Colors Over Hardcoded Values

The principle

Bad (hardcoded white with a dozen opacity values)

Good (semantic system colors)

When you do need opacity

4. Component Sizing: Proportional, Not Oversized

Progress rings / circular indicators

Stroke width consistency

List rows and toggle rows

5. Grouped Content & Cards: Use System Patterns

Bad (over-engineered custom card)

Good (native grouped style)

Key rules for grouped content

6. Navigation: Use NavigationStack

7. WidgetKit: Use Native Components

Circular lock screen widget

Rectangular lock screen widget

Widget background

Widget family coverage

Cross-family visual consistency

Widget memory budget (hard limit)

Timeline refresh (match data granularity)

8. Interactive Elements

Toggles

Mutually exclusive options

Animated transitions for changing numbers

9. Interactive Editors: Centralize Geometry and State

Presentation state

Shared geometry model

Gesture coordination

Fixed editor layout

Custom headers and safe areas

Settings surfaces

10. Data Model: Share Between App and Widgets

11. Quick Checklist

来源与署名

更多Design & Creative技能

Theme Factory

Slack Gif Creator

Frontend Design

Canvas Design

Brand Guidelines

Frontend Design