Duet Tutorial 7: Theming with Design Tokens

version: 1

swift:
  output: src-ios/Libraries/FoyerKit/Sources/Theming/Generated
  engine: DuetTheming
  theme: MainTheme

kotlin:
  output: src-kmp/theming/src/commonMain/kotlin/dev/modaal/foyer/theming/Generated
  package: dev.modaal.foyer.theming
  engine: dev.modaal.duet.services.theming
  palette: MainPalette

colors:
  - group: Surfaces
    tokens:
      - name: surface
        doc: >-
          The page. In the high-contrast theme every card sits directly on
          it.
        light: "#FFFFFF"
        dark: "#121212"
      - name: cardSurface
        doc: >-
          The ground of a card: the Insights card and the plan cards.
        light: "#F1F1EE"
        dark: "#262626"
      - name: lockedSurface
        doc: >-
          The ground of the Insights card while the entitlement is Free.
        note: >-
          A warm wash rather than a grey: the locked state is a state of the
          card, and a colour the eye reads before the lock glyph does.
        light: "#FBF3DC"
        dark: "#3B3320"

  - group: Labels
    tokens:
      - name: labelPrimary
        doc: >-
          Titles on cards: the card's name, the plan's name and price.
        light: "#1A1A1A"
        dark: "#EDEDED"
      - name: labelSecondary
        doc: >-
          Supporting text on cards, one step down: the teaser under the
          card's name.
        light: "#6A6A6A"
        dark: "#9C9C9C"
      - name: labelLocked
        doc: >-
          The lock glyph and the word under a locked card's name.
        light: "#7A5C0A"
        dark: "#E5C15C"

  - group: Chrome
    tokens:
      - name: cardBorder
        doc: >-
          The hairline around every card.
        note: >-
          Translucent, so it reads as a tint of whichever surface the card sits
          on; the high-contrast theme maps it onto the primary label, which
          makes it a solid line of ink.
        light: "#1A1A1A"
        lightAlpha: 0.12
        dark: "#EDEDED"
        darkAlpha: 0.16

fonts:
  - group: The two card styles
    tokens:
      - name: cardTitle
        doc: >-
          The card's name, and the plan's name and price.
        family: sans
        weight: 600
        size: 17
        lineHeight: 22
        swift:
          textStyle: headline
      - name: cardBody
        doc: >-
          The teaser under a card's name.
        family: sans
        weight: 400
        size: 15
        lineHeight: 20
        swift:
          textStyle: subheadline

    .package(url: "https://github.com/modaal-agent/duet-services.git", exact: "0.11.1"),

    // The theming layer: the vocabularies and the value table generated from
    // parity/design-tokens.yaml, the two themes over them, the call-site
    // accessors and the scope that picks the theme from the system setting.
    // iOS-only behind whole-file guards, as the engine is, so the target
    // compiles to nothing in the macOS slice the shells lane builds.
    .target(
      name: "Theming",
      dependencies: [
        .product(name: "DuetTheming", package: "duet-services")
      ],
      swiftSettings: strictConcurrency
    ),

plugins {
  alias(libs.plugins.kotlin.multiplatform)
}

base.archivesName.set("theming")

// The theming module: the token vocabularies and the value table generated
// from parity/design-tokens.yaml (`Generated/`, written by `tools/duet
// design-tokens` and gated by `tools/duet design-tokens --check`), and the
// two themes over them, hand-authored in Theme.kt. The JVM target is the only
// one: the Android app consumes this module's JVM variant, and the iOS app
// reads the same config through its own engine, so no Apple slice has a
// consumer.
kotlin {
  jvmToolchain(25)

  jvm()

  sourceSets {
    commonMain.dependencies {
      // ColorToken and FontToken, the value types the generated table is
      // written in.
      api(libs.duet.services.theming)
    }
    jvmTest.dependencies {
      implementation(kotlin("test"))
    }
  }
}

tasks.withType<Test>().configureEach { useJUnitPlatform() }

public class MainTheme: Themed, Assetable {
  public typealias _ImageAsset = EmptyAsset
  public typealias _GradientAsset = EmptyAsset
}

  public func fontSet(for asset: _FontAsset) -> FontSet {
    let token = fontToken(for: asset)
    let scaled = UIFontMetrics(forTextStyle: token.textStyle).scaledFont(for: token.face)
    return FontSet(
      .static(scaled),
      fontMetrics: FontMetrics(
        pointSize: token.size,
        lineHeight: token.lineHeight,
        // The config states tracking as a fraction of the em; `.pct` is a
        // percentage of the point size, the same quantity times 100.
        letterSpacing: .pct(token.trackingEm * 100)
      )
    )
  }

extension Theme: @retroactive Themeable {
  public static let mainTheme = Theme(key: "mainTheme")
  public static let highContrast = Theme(key: "highContrast")

  public func themed() -> Themed {
    switch self {
    case .mainTheme:
      return MainTheme()
    case .highContrast:
      return HighContrastTheme()
    default:
      fatalError("no theme is registered under the key \(key)")
    }
  }
}

interface Theme {
  fun color(token: SemanticColor): ColorToken

  fun font(token: SemanticFont): FontToken
}

object MainTheme : Theme {
  override fun color(token: SemanticColor): ColorToken = MainPalette.color(token)

  override fun font(token: SemanticFont): FontToken = MainPalette.font(token)
}

fun contrastRatio(a: Long, b: Long): Double {
  val la = relativeLuminance(a)
  val lb = relativeLuminance(b)
  return (maxOf(la, lb) + 0.05) / (minOf(la, lb) + 0.05)
}

  fun everyLabelReadsAtAaOnEveryCard() {
    for (appearance in ResolvedAppearance.entries) {
      for (surface in surfaces) {
        for (label in labels) {
          val ratio = MainTheme.contrast(label, surface, appearance)
          assertTrue(ratio >= 4.5, "$label on $surface at $appearance: ${"%.2f".format(ratio)}")
        }
      }
      val locked = MainTheme.contrast(SemanticColor.labelLocked, SemanticColor.lockedSurface, appearance)
      assertTrue(locked >= 4.5, "labelLocked on lockedSurface at $appearance: ${"%.2f".format(locked)}")
    }
  }

public extension ThemeProviding {
  /// A colour token as a SwiftUI `Color`. Under the system appearance the
  /// colour is dynamic, so a view holding it follows a light/dark switch on
  /// its own.
  func color(_ semanticColor: SemanticColor) -> Color {
    Color(color(for: semanticColor, preferredAppearance: nil, on: nil))
  }

  /// A type token resolved for rendering: the face, the line height and the
  /// tracking together. `.font(theme.font(.cardTitle))` applies all three.
  func font(_ semanticFont: SemanticFont) -> ThemedFont {
    let resolved = font(for: semanticFont, preferredAppearance: nil, on: nil)
    return ThemedFont(face: resolved.font, metrics: resolved.metrics)
  }
}

/** A colour token's value under the theme in effect, at the resolved appearance. */
@Composable
@ReadOnlyComposable
fun SemanticColor.color(): Color = Color(LocalTheme.current.color(this).value(LocalAppearance.current))

/** A type token as a text style, in the platform's face for its family. */
@Composable
@ReadOnlyComposable
fun SemanticFont.textStyle(): TextStyle = LocalTheme.current.font(this).textStyle()

public struct FoyerThemeScope<Content: View>: View {
  @Environment(\.colorSchemeContrast) private var contrast
  private let content: Content

  public init(@ViewBuilder content: () -> Content) {
    self.content = content()
  }

  public var body: some View {
    ThemeScope(contrast == .increased ? FoyerThemes.highContrast : FoyerThemes.main) { content }
  }
}

@MainActor
enum FoyerThemes {
  static let main = provider(for: .mainTheme)
  static let highContrast = provider(for: .highContrast)

  private static func provider(for theme: Theme) -> ThemeProvider {
    ThemeProvider(persistentStorage: Unpersisted(), defaultTheme: theme, defaultPreferredAppearance: .system)
  }
}

fun FoyerTheme(content: @Composable () -> Unit) {
  val dark = isSystemInDarkTheme()
  val theme = if (rememberSystemContrast() > 0f) HighContrastTheme else MainTheme
  CompositionLocalProvider(
    LocalTheme provides theme,
    LocalAppearance provides if (dark) ResolvedAppearance.Dark else ResolvedAppearance.Light,
  ) {
    MaterialTheme(colorScheme = if (dark) darkColorScheme() else lightColorScheme(), content = content)
  }
}

private fun rememberSystemContrast(): Float {
  if (Build.VERSION.SDK_INT < Build.VERSION_CODES.UPSIDE_DOWN_CAKE) return 0f
  val context = LocalContext.current
  val manager = remember(context) { context.getSystemService(UiModeManager::class.java) }
  var contrast by remember(manager) { mutableFloatStateOf(manager.contrast) }
  DisposableEffect(manager) {
    val listener = UiModeManager.ContrastChangeListener { contrast = it }
    manager.addContrastChangeListener(context.mainExecutor, listener)
    onDispose { manager.removeContrastChangeListener(listener) }
  }
  return contrast
}

      - name: tools/duet design-tokens --check
        run: tools/duet design-tokens --check

      - name: theming tests
        run: (cd src-kmp && ./gradlew :theming:jvmTest --console=plain -q)