Diagonal strategy (compose.diagonal / code.diagonal)

August 30, 2026 · View on GitHub

Artifact: io.github.bodenberg:appdimens-kmp-diagonal:3.2.0 (:library-diagonal) See MODULES.md · README installation

Same API surface as scaled with prefixes dgsdp / dghdp / dgwdp / dgssp / … — see COMPOSE-API-CONVENTIONS.md §3.

What it is

Diagonal scales by the length of the screen rectangle’s diagonal in dp: it combines width and height into one number, reflecting “perceived canvas size” better than a single axis alone. The SDP/HDP/WDP qualifier does not change the diagonal used — the math always uses the current window’s shorter and longer side.

Calculation used

Mathematically, for the current window:

  • shorter = min(widthDp, heightDp), longer = max(...)
  • diag = √(shorter² + longer²)
  • scale = diag / BASE_DIAGONAL_DP with BASE_DIAGONAL_DP = √(300² + 533²) ≈ 611.63 (DesignScaleConstants).
  • out = base × scale.

Implementation note: scale is derived from the immutable per-window snapshot (DimenCache.currentMetrics) at resolution time — no process-global pre-computation. The steps above describe what that factor represents; the default path does not recompute √(shorter² + longer²) on every call.

  • With a: multiply by the per-window aspect-ratio factor (DimenCache.currentAspectRatioMul, derived in the immutable DimenMetrics snapshot); custom sensitivity uses 1+k×logNormalizedAr1 + \text{k} \times \text{logNormalizedAr}.

Implementation: calculateDiagonalDpCompose in DimenDiagonalDp.kt.

How to use

import com.appdimens.kmp.compose.diagonal.dgsdp

Modifier.size(64.dgsdp)

Main Compose prefixes: dgsdp, dghdp, dgwdp (plus a / i / ia, Px, inverters like .dgsdpPh, .dgsdpLw, … in DimenDiagonalDp.kt).

Code: com.appdimens.kmp.code.diagonal.

Why use it

Elements that should react to overall canvas size (games, dense dashboards, frames) rather than width or height alone.

When to use it

  • Balance wide short vs tall narrow screens fairly.
  • When sdp or wdp alone skew visual hierarchy.

Advantages and trade-offs

  • Pros: one stable scalar for “how big is the screen” overall.
  • Cons: less intuitive for designers used to width breakpoints; inverters have limited effect on the diagonal itself (the read axis changes, but the formula still uses the current sides).

Reserve diagonal for specific components (e.g. board piece size, centered hero icon); keep lists and running text on scaled or hdp/wdp depending on the dominant axis.

Back to index