swift-front/references/hig-color.md

HIG: Color & Dark Mode

Source: Apple HIG — Color | 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