# 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