Visual overview

Use the workflow to follow the task, and the architecture map to separate responsibilities. These are conceptual maps; the guide below defines implementation details and verification limits.

01 / WorkflowFrom intent to a checked result
  1. Choose base surfaces
  2. Separate raised layers
  3. Check both appearances
  4. Inspect accessibility settings
02 / ArchitectureResponsibility boundaries
  1. Boundary 1Named assets
  2. Boundary 2Appearance resolution
  3. Boundary 3Native containers

Connected responsibilities, not a required class hierarchy or an execution trace.

Context

A dark palette is not an RGB inverse. The generator independently assigns a dark base, raised and grouped surfaces, text and state colors. The primary seed retains its hue identity while foreground roles are adjusted for contrast.

Pattern

Use named asset colors with Any and Dark values. The existing asset schema also requires highContrastLight and highContrastDark; these map to Xcode's contrast appearance selectors. Keep the same semantic role across appearances. A light brand blue can become lighter in dark mode while the button foreground changes to black.

OLED preference sets only the dark base to black. Elevated and grouped surfaces remain visible. Do not assume black alone reduces energy consumption for every device or screen composition. Shadows are not reliable separation on a black base; use native materials, spacing or appropriate boundaries.

For native lists prefer UIColor.systemGroupedBackground and the secondary/tertiary system grouped backgrounds. In SwiftUI .primary, .secondary, .background and system materials adapt to context. The custom SurfaceOverlay token is an opaque fallback, not a substitute for blur or Liquid Glass.

Verification sequence

  1. Inspect text, buttons, selection and status indicators in Any and Dark.
  2. Turn on Increase Contrast; check the selected asset variants and native material changes.
  3. Turn on Differentiate Without Color; selected and error states need icons, labels or shape cues.
  4. Increase Dynamic Type and check truncation, alignment and touch targets separately.
  5. Check toolbar, navigation and tab tint in actual native containers. Avoid coloring every symbol or toolbar background manually.

SwiftUI tint is the preferred control-level customization where supported. Color.accentColor reads the asset accent; it is not a guarantee that every control is tinted identically. For SF Symbols retain hierarchical/monochrome system rendering unless palette rendering carries meaning that remains understandable without color.

Sources

Apple UIColor, SwiftUI Color, and Xcode color-scheme setup describe adaptive color and appearance assets. Consult the HIG Dark Mode page when evaluating the finished UI; its JavaScript-only content was not used as evidence of new requirements in this implementation.