Initial release: swift-front skill with Apple HIG integration

Combines frontend-design aesthetics with swiftui-pro correctness,
grounded in Apple's Human Interface Guidelines (134 articles).

Includes curated HIG reference files for typography, color, layout,
materials, motion, icons, and components, plus full HIG JSON data
for deep lookups.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Anthony Cardinale
2026-03-25 07:52:07 -04:00
commit 34bd90e30d
18 changed files with 51322 additions and 0 deletions
+94
View File
@@ -0,0 +1,94 @@
# HIG: Color & Dark Mode
Source: [Apple HIG — Color](https://developer.apple.com/design/human-interface-guidelines/color) | [Dark Mode](https://developer.apple.com/design/human-interface-guidelines/dark-mode)
## Best Practices
- Don't use the same color to mean different things — use color consistently for status and interactivity
- All colors must work in light, dark, AND increased contrast contexts
- Even single-appearance apps must provide both light and dark colors for Liquid Glass adaptivity
- Test colors under different lighting conditions (bright sunlight, dim light)
- Test on multiple devices (True Tone displays adapt white point)
- Avoid hard-coding system color values — use `Color` API
- Use wide color (Display P3) for richer, more saturated colors on compatible displays
- Use asset catalog Color Sets with light/dark variants
## Inclusive Color
- Never rely solely on color to differentiate objects or communicate info
- Provide text labels, glyph shapes, or patterns as alternatives
- Ensure sufficient contrast so icons and text don't blend with background
- Consider cultural color meanings (red = danger in some cultures, positive in others)
## System Colors (SwiftUI)
red, orange, yellow, green, mint, teal, cyan, blue, indigo, purple, pink, brown
- visionOS uses default dark color values
- iOS/iPadOS has 6 system grays: `gray` (SwiftUI) = `systemGray` (UIKit), plus `systemGray2`-`systemGray6`
## iOS/iPadOS Dynamic Background Colors
Two sets — **system** and **grouped** — each with primary, secondary, tertiary:
| Level | Use for |
|-------|---------|
| Primary | Overall view background |
| Secondary | Grouping content within the overall view |
| Tertiary | Grouping content within secondary elements |
Use **grouped** set with grouped table views; **system** set otherwise.
## Foreground Colors (iOS)
| Color | Use | UIKit API |
|-------|-----|-----------|
| Label | Primary content text | `label` |
| Secondary label | Secondary content | `secondaryLabel` |
| Tertiary label | Tertiary content | `tertiaryLabel` |
| Quaternary label | Quaternary content | `quaternaryLabel` |
| Placeholder text | Control placeholders | `placeholderText` |
| Separator | Allows underlying content through | `separator` |
| Opaque separator | Fully opaque | `opaqueSeparator` |
| Link | Hyperlink text | `link` |
## Liquid Glass Color
- Liquid Glass has no inherent color — takes on colors from content behind it
- Apply color sparingly — reserve for emphasis (status indicators, primary actions)
- For primary actions, color the background (not symbols/text)
- Don't apply color to multiple control backgrounds
- Symbols/text on Liquid Glass can have color (e.g., selected tab bar item)
- Avoid similar colors in control labels over colorful backgrounds — prefer monochromatic
## Color Management
- Apply color profiles to images (sRGB for most, Display P3 for wide color)
- Wide color: P3 profile at 16 bits/channel, export as PNG
- Provide color space-specific variants if P3 gradients appear clipped on sRGB displays
## Dark Mode
- Don't offer app-specific appearance toggle — respect system setting
- Ensure content is legible in both modes, including with Increase Contrast + Reduce Transparency
- Dark palette uses dimmer backgrounds, brighter foregrounds (not simple inversions)
- Use semantic Color Set assets with light/dark variants — avoid hard-coded values
- Minimum contrast ratio: 4.5:1; aim for 7:1 especially in small text
- Soften white backgrounds slightly to prevent glowing in dark contexts
### iOS/iPadOS Dark Mode
- Two background levels: **base** (dimmer, recedes) and **elevated** (brighter, advances)
- System auto-switches base to elevated for popovers, modal sheets, foreground apps
- Use system background colors to maintain these visual distinctions
### macOS Dark Mode
- Desktop tinting: window backgrounds pick up color from desktop picture (graphite accent)
- Add transparency to custom component backgrounds (neutral state only) for tinting harmony
## Platform-Specific Notes
- **tvOS:** Limited color palette coordinating with app logo; don't use only color to indicate focus
- **visionOS:** Use color sparingly on glass; prefer bold text/large areas; keep brightness balanced
- **watchOS:** Background color should communicate, not just decorate; avoid full-screen background color in long-duration views
+62
View File
@@ -0,0 +1,62 @@
# HIG: Components & Patterns
Source: [Apple HIG — Components](https://developer.apple.com/design/human-interface-guidelines/components) | [Modality](https://developer.apple.com/design/human-interface-guidelines/modality) | [Searching](https://developer.apple.com/design/human-interface-guidelines/searching)
## Component Categories
### Content
Charts, Image views, Text views, Web views
### Layout and Organization
Boxes, Collections, Column views, Disclosure controls, Labels, Lists and tables, Lockups, Outline views, Split views, Tab views
### Menus and Actions
Activity views, Buttons, Context menus, Dock menus, Edit menus, Home Screen quick actions, Menus, Ornaments, Pop-up buttons, Pull-down buttons, The menu bar, Toolbars
### Navigation and Search
Path controls, Search fields, Sidebars, Tab bars, Token fields
### Presentation
Action sheets, Alerts, Page controls, Panels, Popovers, Scroll views, Sheets, Windows
### Selection and Input
Color wells, Combo boxes, Digit entry views, Image wells, Pickers, Segmented controls, Sliders, Steppers, Text fields, Toggles, Virtual keyboards
### Status
Activity rings, Gauges, Progress indicators, Rating indicators
### System Experiences
App Shortcuts, Complications, Controls, Live Activities, Notifications, Status bars, Top Shelf, Watch faces, Widgets
## Modality
### When to Use
- Deliver critical information requiring acknowledgment
- Confirm/modify a recent action
- Help people perform a distinct, narrowly scoped task
- Provide immersive experience or aid concentration
### Best Practices
- Present modally only when there's a **clear benefit**
- Keep modal tasks **simple, short, and streamlined**
- Avoid hierarchy within modals — single path only
- Full-screen modal for in-depth content or complex tasks
- Always provide an **obvious dismiss mechanism**
- Confirm before closing if dismissal could lose user content
- Never stack modals — dismiss one before showing another
- Only one alert visible at a time
## Searching
### Best Practices
- If search is important, make it a **primary action** (tab bar, toolbar)
- Single search location — one clearly identified place
- Placeholder text to indicate searchable content
- Display current scope clearly
- Provide suggestions before and during typing
- Consider privacy — provide option to clear search history
## Navigation Conventions
- Standard Back and Close buttons with system symbols
- Don't use text labels for Back/Close — use symbols
- Consistent implementation throughout the app
+91
View File
@@ -0,0 +1,91 @@
# HIG: Icons & SF Symbols
Source: [Apple HIG — App Icons](https://developer.apple.com/design/human-interface-guidelines/app-icons) | [Icons](https://developer.apple.com/design/human-interface-guidelines/icons) | [SF Symbols](https://developer.apple.com/design/human-interface-guidelines/sf-symbols)
## App Icons
### Layer Design
- iOS/iPadOS/macOS/watchOS: background + foreground layers with Liquid Glass effects
- tvOS: 2-5 layers for parallax
- visionOS: background + 1-2 layers as 3D object
### Key Rules
- Embrace simplicity — simple icons are easiest to recognize
- Keep primary content centered to avoid masking truncation
- Prefer filled, overlapping shapes for depth
- Include text only when essential to brand
- Use illustrations, not photos or UI screenshots
- Let the system handle visual effects (highlights, shadows, bevels)
### Specifications
| Platform | Shape | Size | Appearances |
|----------|-------|------|-------------|
| iOS/iPadOS/macOS | Rounded rect | 1024x1024 px | Default, dark, clear, tinted |
| tvOS | Rounded rect | 800x480 px | N/A |
| visionOS | Circular | 1024x1024 px | N/A |
| watchOS | Circular | 1088x1088 px | N/A |
## Interface Icons
- Simple, recognizable, highly simplified designs
- Consistent size, detail, stroke weight, perspective across all icons
- Match icon weight to adjacent text weight
- Use vector format (PDF/SVG) — scales automatically
- Provide accessibility descriptions for custom icons
## SF Symbols (6000+)
### Rendering Modes
| Mode | Description |
|------|-------------|
| **Monochrome** | One color for all layers |
| **Hierarchical** | One color, varying opacity per layer |
| **Palette** | Two or more colors, one per layer |
| **Multicolor** | Intrinsic colors (leaf=green, trash.slash=red) |
### Gradients (SF Symbols 7+)
Linear gradient from single color, all rendering modes, best at larger sizes.
### Variable Color
Represents changing values (0-100%): layers receive color at thresholds.
Use for **change**, NOT depth (use Hierarchical for depth).
### Design Variants
- **Outline:** Text-like (toolbars, lists)
- **Fill:** Solid areas (tab bars, swipe actions, selection)
- **Slash:** Unavailability
- **Enclosed:** Circle/square (legibility at small sizes)
System views auto-select variant (tab bar -> fill, toolbar -> outline).
### Animations
| Animation | Use For |
|-----------|---------|
| Appear/Disappear | Gradual show/hide |
| Bounce | Feedback that action occurred |
| Scale | Draw attention to selection |
| Pulse | Ongoing activity |
| Variable color | Progress, broadcasting |
| Replace/Magic Replace | Swap symbols with transitions |
| Wiggle | Highlight change or call to action |
| Breathe | Status changes, ongoing recording |
| Rotate | Progress indicators |
| Draw On/Off | Progress, direction (SF Symbols 7+) |
### Common Standard Symbols
| Action | Symbol |
|--------|--------|
| Add | `plus` |
| Delete | `trash` |
| Share | `square.and.arrow.up` |
| Search | `magnifyingglass` |
| Done | `checkmark` |
| Cancel | `xmark` |
| Compose | `square.and.pencil` |
| More | `ellipsis` |
| Filter | `line.3.horizontal.decrease` |
| Account | `person.crop.circle` |
+100
View File
@@ -0,0 +1,100 @@
# HIG: Layout
Source: [Apple HIG — Layout](https://developer.apple.com/design/human-interface-guidelines/layout)
## Best Practices
- Group related items using negative space, background shapes, colors, materials, or separators
- Give essential information sufficient space — don't crowd with nonessential details
- Extend content to fill screen/window edges — backgrounds and artwork should be full-bleed
- Scrollable layouts should continue to bottom and sides of device screen
- Controls (sidebars, tab bars) appear ON TOP of content, not on the same plane
## Visual Hierarchy
- Use Liquid Glass material for controls/navigation — distinct from content layer
- Use scroll edge effects (not backgrounds) to transition between content and control areas
- Place items in reading order (top-to-bottom, leading-to-trailing) — most important near top/leading
- Align components for easier scanning — alignment communicates organization
- Use progressive disclosure for hidden content (disclosure controls, partial item display)
- Provide enough space around controls — crowded controls are hard to distinguish
## Adaptability
Handle these variations:
- Different screen sizes, resolutions, color spaces
- Portrait/landscape orientations
- Dynamic Island, camera controls
- External displays, Display Zoom, resizable iPad windows
- Dynamic Type text-size changes
- RTL layout, internationalization
Use SwiftUI layout or Auto Layout for adaptive interfaces. Respect safe areas, margins, and guides.
## Guides & Safe Areas
- **Layout guides:** Rectangular regions for positioning/aligning content
- **Safe areas:** Regions not covered by bars, Dynamic Island, camera housing
- Always respect safe areas — content outside feels wrong and may be hard to use
## iOS
- Support both portrait and landscape (or commit to one)
- Full-bleed game interfaces accommodating corner radius, sensor housing, Dynamic Island
- Avoid full-width buttons — respect system margins, match hardware curvature
- Keep status bar visible unless immersive experience
## iPadOS
- Windows freely resizable — account for full range of sizes
- Defer compact view as long as possible — hide tertiary columns first
- Test at common system sizes (halves, thirds, quadrants)
- Consider convertible tab bar (sidebar <-> tab bar)
## visionOS
- Center important content and controls in windows
- Keep content within window bounds (system controls are OUTSIDE bounds)
- Use ornaments for controls outside the window
- Space interactive components with centers at least 60pt apart
## watchOS
- Extend content edge-to-edge — bezel provides natural padding
- Max 3 glyph buttons or 2 text buttons side-by-side
## Key Device Dimensions (Current Models)
| Device | Points (portrait) | Pixels | Scale |
|--------|-------------------|--------|-------|
| iPhone 17 Pro Max | 440x956 | 1320x2868 | @3x |
| iPhone 17 Pro | 402x874 | 1206x2622 | @3x |
| iPhone Air | 420x912 | 1260x2736 | @3x |
| iPhone 16 Pro Max | 440x956 | 1320x2868 | @3x |
| iPhone 16 | 393x852 | 1179x2556 | @3x |
| iPhone SE | 375x667 | 750x1334 | @2x |
| iPad Pro 12.9" | 1024x1366 | 2048x2732 | @2x |
| iPad Pro 11" | 834x1194 | 1668x2388 | @2x |
| iPad Air 13" | 1024x1366 | 2048x2732 | @2x |
| iPad Air 11" | 820x1180 | 1640x2360 | @2x |
| iPad mini 8.3" | 744x1133 | 1488x2266 | @2x |
## Size Classes
| Device Type | Portrait | Landscape |
|-------------|----------|-----------|
| All iPads | Regular W, Regular H | Regular W, Regular H |
| iPhone Pro Max/Plus/Air | Compact W, Regular H | Regular W, Compact H |
| iPhone Pro/standard/mini | Compact W, Regular H | Compact W, Compact H |
## tvOS Grid Spacing
All grids: 40pt horizontal spacing, 100pt minimum vertical spacing.
| Columns | Unfocused Content Width |
|---------|------------------------|
| 2 | 860 pt |
| 3 | 560 pt |
| 4 | 410 pt |
| 5 | 320 pt |
| 6 | 260 pt |
+82
View File
@@ -0,0 +1,82 @@
# HIG: Materials
Source: [Apple HIG — Materials](https://developer.apple.com/design/human-interface-guidelines/materials)
## Overview
Two types of materials:
1. **Liquid Glass** — Dynamic material for controls/navigation (tab bars, sidebars, toolbars)
2. **Standard materials** — For visual differentiation within the content layer
## Liquid Glass
Forms a distinct functional layer floating above content. Content scrolls and peeks through.
### Rules
- **Don't** use Liquid Glass in the content layer — controls/navigation only
- Exception: transient interactive elements (sliders, toggles) take Liquid Glass when activated
- Use sparingly — system components get it automatically
- Only apply to custom controls for the most important functional elements
### Variants
| Variant | Appearance | Use When |
|---------|-----------|----------|
| **Regular** | Blurs + adjusts luminosity | Background might affect legibility; significant text (alerts, sidebars, popovers) |
| **Clear** | Highly translucent | Floating over media (photos, videos) for immersive experience |
### Clear Variant Dimming
- Bright underlying content: add dark dimming layer at 35% opacity
- Dark underlying content or AVKit controls: no dimming needed
### Color on Liquid Glass
- No inherent color — takes on colors from content behind it
- Apply color sparingly — reserve for primary actions (Done button accent)
- Color the background, not symbols/text
- Don't color multiple control backgrounds
## Standard Materials
### iOS/iPadOS
Four levels (content layer only): ultra-thin, thin, regular (default), thick
**Vibrancy for labels:** `label`, `secondaryLabel`, `tertiaryLabel`, `quaternaryLabel`
**Vibrancy for fills:** `fill`, `secondaryFill`, `tertiaryFill`
Avoid `quaternaryLabel` on thin/ultraThin (too low contrast).
### macOS
- Several standard materials with designated purposes
- Two blending modes: **behind window** and **within window**
### tvOS
| Material | Recommended For |
|----------|----------------|
| ultraThin | Full-screen views, light scheme |
| thin | Overlays, light scheme |
| regular | General overlays |
| thick | Overlays, dark scheme |
### visionOS
- Windows use system **glass** material (unmodifiable, adaptive)
- No distinct Dark Mode — glass adapts to luminance behind it
- Prefer translucency over opaque colors
- Custom component materials: thin (interactive), regular (separations), thick (dark distinct)
- Vibrancy: `label`, `secondaryLabel`, `tertiaryLabel`
### watchOS
- Use materials for context in full-screen modal views
- Don't remove default material backgrounds from modal sheets
## SwiftUI API
- `.ultraThinMaterial`, `.thinMaterial`, `.regularMaterial`, `.thickMaterial`, `.ultraThickMaterial`
- Liquid Glass: `glassEffect(_:in:)`
+45
View File
@@ -0,0 +1,45 @@
# HIG: Motion
Source: [Apple HIG — Motion](https://developer.apple.com/design/human-interface-guidelines/motion)
## Best Practices
- Add motion **purposefully** — don't add for its own sake
- Make motion **optional** — never the only way to communicate information
- Supplement visual feedback with haptics and audio alternatives
- Liquid Glass responds differently to touch (more emphasis) vs trackpad (more subdued)
## Feedback
- Strive for **realistic** feedback following gestures and expectations
- Aim for **brevity and precision** — succinct animations convey info without distraction
- Avoid adding motion to **frequently used UI interactions** — system handles standard animations
- Let people **cancel motion** — don't force waiting for animations to complete
- Consider **animated SF Symbols** (SF Symbols 5+)
## Accessibility
- If `accessibilityReduceMotion` is enabled, replace large motion with **opacity crossfades**
- Non-negotiable for accessibility compliance
## visionOS Motion
- Avoid motion at edges of field of view — peripheral motion causes discomfort
- For large moving objects, increase translucency or lower contrast
- Use **fades** to relocate objects (fade out, move, fade in)
- Avoid letting people rotate virtual worlds — disrupts stability
- Provide a **stationary frame of reference** — contained movement is more comfortable
- Avoid sustained oscillation (especially ~0.2 Hz)
## watchOS
- SwiftUI provides streamlined motion APIs
- All layout/appearance animations include **built-in easing** (can't customize)
## Design Principles
1. Motion should **reinforce understanding** of how something works
2. **Brief and precise** over prominent and elaborate
3. Let system handle standard interaction animations
4. Custom animation for **unique moments** only (reveals, transitions, celebrations)
5. Always respect Reduce Motion accessibility setting
+111
View File
@@ -0,0 +1,111 @@
# HIG: Typography
Source: [Apple HIG — Typography](https://developer.apple.com/design/human-interface-guidelines/typography)
## System Fonts
- **San Francisco (SF):** SF Pro, SF Compact, SF Mono, SF Arabic, SF Armenian, SF Georgian, SF Hebrew — plus Rounded variants
- **New York (NY):** Serif family, works well alongside SF
- Variable font format with dynamic optical sizes — no need to pick discrete optical sizes
## Default & Minimum Text Sizes
| Platform | Default | Minimum |
|----------|---------|---------|
| iOS, iPadOS | 17 pt | 11 pt |
| macOS | 13 pt | 10 pt |
| tvOS | 29 pt | 23 pt |
| visionOS | 17 pt | 12 pt |
| watchOS | 16 pt | 12 pt |
## Text Styles (iOS/iPadOS — Large/Default)
| Style | Weight | Size | Leading | Emphasized |
|-------|--------|------|---------|------------|
| Large Title | Regular | 34 pt | 41 pt | Bold |
| Title 1 | Regular | 28 pt | 34 pt | Bold |
| Title 2 | Regular | 22 pt | 28 pt | Bold |
| Title 3 | Regular | 20 pt | 25 pt | Semibold |
| Headline | Semibold | 17 pt | 22 pt | Semibold |
| Body | Regular | 17 pt | 22 pt | Semibold |
| Callout | Regular | 16 pt | 21 pt | Semibold |
| Subhead | Regular | 15 pt | 20 pt | Semibold |
| Footnote | Regular | 13 pt | 18 pt | Semibold |
| Caption 1 | Regular | 12 pt | 16 pt | Semibold |
| Caption 2 | Regular | 11 pt | 13 pt | Semibold |
## macOS Text Styles
| Style | Weight | Size | Line Height | Emphasized |
|-------|--------|------|-------------|------------|
| Large Title | Regular | 26 pt | 32 pt | Bold |
| Title 1 | Regular | 22 pt | 26 pt | Bold |
| Title 2 | Regular | 17 pt | 22 pt | Bold |
| Title 3 | Regular | 15 pt | 20 pt | Semibold |
| Headline | Bold | 13 pt | 16 pt | Heavy |
| Body | Regular | 13 pt | 16 pt | Semibold |
| Callout | Regular | 12 pt | 15 pt | Semibold |
| Subheadline | Regular | 11 pt | 14 pt | Semibold |
| Footnote | Regular | 10 pt | 13 pt | Semibold |
| Caption 1 | Regular | 10 pt | 13 pt | Medium |
| Caption 2 | Medium | 10 pt | 13 pt | Semibold |
## tvOS Text Styles
| Style | Weight | Size | Leading | Emphasized |
|-------|--------|------|---------|------------|
| Title 1 | Medium | 76 pt | 96 pt | Bold |
| Title 2 | Medium | 57 pt | 66 pt | Bold |
| Title 3 | Medium | 48 pt | 56 pt | Bold |
| Headline | Medium | 38 pt | 46 pt | Bold |
| Subtitle 1 | Regular | 38 pt | 46 pt | Medium |
| Callout | Medium | 31 pt | 38 pt | Bold |
| Body | Medium | 29 pt | 36 pt | Bold |
| Caption 1 | Medium | 25 pt | 32 pt | Bold |
| Caption 2 | Medium | 23 pt | 30 pt | Bold |
## Best Practices
- Avoid light font weights (Ultralight, Thin, Light) — prefer Regular, Medium, Semibold, Bold
- Minimize the number of typefaces — too many obscures hierarchy
- Use `bold()` in SwiftUI (not `fontWeight(.bold)`) so the system picks context-appropriate weight
- Use `Font.Design.default` for system font, `Font.Design.serif` for New York
- Don't embed system fonts — use the APIs
## Dynamic Type
- System-level feature in iOS, iPadOS, tvOS, visionOS, watchOS
- Text styles scale proportionately when people change text size
- Support Larger Accessibility Text Sizes (AX1-AX5 go up to 60pt body)
- Consider adjusting layout at large sizes (stack horizontally placed items vertically)
- Keep text truncation minimal — display as much useful text as possible
- Maintain consistent information hierarchy regardless of font size
- Use `isAccessibilityCategory` to detect when accessibility sizes are active
## Custom Fonts
- Always use `relativeTo:` with `.font(.custom())` to support Dynamic Type
- Use `@ScaledMetric` (iOS 18-) or `.font(.body.scaled(by:))` (iOS 26+) for custom sizing
- Implement accessibility features (Bold Text, Dynamic Type) for custom fonts
## visionOS Specifics
- Uses bolder body and title styles, plus Extra Large Title 1 and 2
- Prefer 2D text — 3D text is harder to read
- Use billboarding for text associated with spatial objects
- Maximize contrast between text and container background
## Tracking Values (SF Pro — Key Sizes)
| Size | Tracking (pt) |
|------|--------------|
| 11 pt | +0.06 |
| 12 pt | 0.0 |
| 13 pt | -0.08 |
| 17 pt (body) | -0.43 |
| 22 pt | -0.26 |
| 28 pt | +0.38 |
| 34 pt | +0.40 |
| 48 pt | +0.35 |
| 72 pt | +0.14 |
| 96 pt | 0.0 |