Understanding semantic tokens

A semantic token names the job a color does, such as a title or a card's background, instead of the color itself. Every theme has the same 20 tokens, each with one stop for light mode and one for dark, so a color picked by its job, like theme.foregroundPrimary, switches with dark mode and keeps its contrast in any theme.

Four kinds of token#

Here's a booking card with every part labeled by the token that colors it. Switch to dark mode and every part moves to its dark stop:

• Foreground: text and icons, from foregroundPrimary for titles and body text to foregroundTertiary for hints and labels.
• Background: the solid areas text sits on: the page, cards, tags.
• Surface: see-through layers over other content, such as a pill on a photo, a sheet or a tooltip.
• Outline: edges and dividers. outlinePrimary marks a control's edge; outlineSecondary and outlineTertiary are decorative lines.

Foreground, background and surface each have an inverted twin, for an area in the opposite mode: a filled button, an avatar, or a dark banner on a light screen.

All 20 tokens#

Drag across the themes to see each token's stop and Display P3 hex in any family. Surfaces let what's behind them show through, so they're drawn over each mode's page color.

ColorTokens.swift also puts the 20 names on Color, built on gray, for parts of your app outside any theme. Color.backgroundPrimary is pure white and black.

Contrast of token pairs#

A stop has the same lightness in every hue, so a pair of tokens has the same contrast in every family, including your own. Here's every pair, drawn in proBlue, with its ratio in each mode:

Keep foregrounds on backgrounds and inverted foregrounds on inverted backgrounds. Crossed over, text vanishes: foregroundPrimary on invertedBackgroundPrimary is 1.00:1 in dark mode.

Gray's ramp runs from white to black, so every gray pair passes AA. Over backgroundPrimary, every foreground token passes AA on every surface too. Over invertedBackgroundPrimary, invertedForegroundTertiary on invertedSurfacePrimary falls as low as 3.49:1.

outlinePrimary is for edges people need to find a control, like a text field's border, so it reaches 3:1 on every background token in both modes. outlineSecondary and outlineTertiary are for dividers and card edges, lines WCAG sets no minimum for, so they stay faint. Borders people need to see has an example.

Adding your own tokens#

The tokens live in ColorTokens.swift, a file you copy into your app, so you can rename them, move them or add your own. A token is a property on ProTheme with one stop for each mode. Keep its stops at least 12 from the background they sit on, and it passes AA in every hue by the distance rule:

public extension ProTheme {
    /// Links in running text. Color(light:dark:) takes a Color for each mode,
    /// so each stop gets toColor().
    var accentText: Color {
        // 5.11:1 on backgroundPrimary in light mode, 7.91:1 in dark
        Color(light: _650.toColor(), dark: _350.toColor())
    }
}

Text("See all trips")
    .foregroundStyle(brand.accentText)
    .padding()
    .background(brand.backgroundPrimary)   // _50 in light mode, _1000 in dark

Next steps

• Using your first tokens Color text, buttons, cards and lists with tokens, then theme a movie card in one line.
• Managing dark mode Get dark mode without extra code: tokens switch stops for you, and your own colors can too.
• Setting up themes Recolor a view, a screen or your whole app from one value, with the same contrast in every hue.
• .contrastRatio(to:method:) Check WCAG 2 and APCA contrast in Swift, and keep your color pairs passing with a unit test.