Add a single geometry token file and a test that enforces it

Introduce ui/theme/Dimens.kt as the one source of truth for app geometry,
alongside Typography.kt for type. It defines the 4dp spacing scale
(SPACING_XXS/XS/S/M/L/XL/XXL) and receives the geometry constants that
already existed, each with a comment tying it to what it is: PEEK_WIDTH_DP
(the collapsed strip), PEEK_BUDGET_DP, MIN_ACTIVE_PANE_WIDTH_DP and
MIN_COVERED_PANE_WIDTH_DP from SlidingPaneStack.kt, DESTINATION_PILL_RESERVE
from PipelinesApp.kt, and WIDE_RAIL_WIDTH_DP and DETAIL_MAX_WIDTH_DP from
DetailTabs.kt. Call sites now import the tokens; every value is unchanged,
so no layout changes.

Add ui/theme/DimensTest.kt, a JVM test that scans the app's Kotlin sources
for raw dp/sp literals and fails with file:line:literal unless the literal
is a token or an explicit, reasoned allow-list entry. The allow-list records
the 34 literals that predate the token file, each with a written reason, and
is expected to shrink as call sites migrate onto the tokens.

Document the change and its verification in android/README.md.
This commit is contained in:
2026-10-16 11:50:26 +01:00
parent d019213c5b
commit f6b9424894
7 changed files with 337 additions and 29 deletions
+73
View File
@@ -2248,3 +2248,76 @@ Not verified in this pass: a clean *settled* frame of the selected-row highlight
only a transient mid-fade frame was captured); resume-after-pause of an
in-flight animation on device (the pause is Compose's own recomposer behaviour,
not code here).
## One source of truth for app geometry, with an enforcement test (16 Oct 2026)
`android/` only. No layout changed: every moved value is identical, so the app
renders exactly as before. No new dependency, no server/Go/installer/Docker file
touched, no run started from the app.
- **`ui/theme/Dimens.kt`** is the single source of truth for app geometry,
alongside `Typography.kt` for type. It defines the 4dp **spacing scale**
(`SPACING_XXS`/`XS`/`S`/`M`/`L`/`XL`/`XXL`, each comment tied to that base
step) and moves the geometry constants that already existed:
`PEEK_WIDTH_DP` (the collapsed/peek strip), `PEEK_BUDGET_DP`,
`MIN_ACTIVE_PANE_WIDTH_DP`, `MIN_COVERED_PANE_WIDTH_DP` (from
`SlidingPaneStack.kt`), `DESTINATION_PILL_RESERVE` (from `PipelinesApp.kt`),
`WIDE_RAIL_WIDTH_DP` and `DETAIL_MAX_WIDTH_DP` (from `DetailTabs.kt`). The
removed `LIST_PANE_WIDTH`, `COLLAPSED_LIST_PANE_WIDTH` and
`COLLAPSED_RAIL_WIDTH_DP` no longer exist, so there was nothing to move for
the "list pane width" or the rail's collapsed width; the collapsed *strip*
that survives is `PEEK_WIDTH_DP`. Call sites import the tokens; their values
(`56/224/320/112/88/200/840`) are unchanged.
- **`ui/theme/DimensTest.kt`** scans the app's Kotlin sources
(`src/main/java`, excluding `Dimens.kt`) for raw `dp`/`sp` literals, masking
comment and string contents first so prose and URLs are not hits. It
allow-lists the 34 literals that predate the file, each with a written reason
(structural zeros/hairlines, the 4dp-scale members that are not yet migrated,
component glyph sizes, the workflow-graph's own pixel geometry, container
sizes and the `sp` typography values owned by `Typography.kt`). A literal that
is neither a token nor allow-listed fails with `file:line: literal`. The list
is expected to shrink as call sites move onto the tokens.
Evidence (macOS, JDK 17 from Homebrew `openjdk@17`,
`ANDROID_HOME=~/Library/Android/sdk`, Gradle 9.7.1, `--offline`):
- `gradle :app:assembleDebug :app:testDebugUnitTest --rerun-tasks --console=plain`
→ `BUILD SUCCESSFUL`; `--rerun-tasks` re-ran all 24 result XMLs to **188 tests,
0 failures, 0 errors, 0 skipped** (up from 186/23; the new `DimensTest` adds
`rawDimensionLiteralsAreTokensOrReasonedAllowListEntries` and
`everyAllowListEntryHasAWrittenReason`).
`app/build/outputs/apk/debug/app-debug.apk` is 17,929,473 bytes, sha256
`e52ceb25…`.
- **Enforcement proof.** Adding `private val PROBE_RAW_LITERAL = 123.dp` to
`ui/PipelinesApp.kt` made
`gradle :app:testDebugUnitTest --tests net.awan.pipelines.ui.theme.DimensTest`
`FAILED` with
`raw dimension literals outside net/awan/pipelines/ui/theme/Dimens.kt: [net/awan/pipelines/ui/PipelinesApp.kt:455: 123.dp]`
(file, line and literal); removing the line made the same task
`BUILD SUCCESSFUL`. The probe was reverted.
- **Before/after screenshots on `emulator-5554` only** (fold AVD, 2076x2152 /
390dpi; never the attached Pixel, never `emulator-5556`), against the live
server, each frame captured and validated with
`scripts/capture_png.sh -s emulator-5554`: the **before** APK was built from
HEAD `d019213` (android changes stashed, built, then restored) and the
**after** APK from the working tree, each installed with
`adb -s emulator-5554 install -r`, force-stopped and relaunched. Screen A is
the Pipelines list; screen B is the "Complete a Task" pipeline detail (the
wide rail plus the covered list peek, i.e. the moved rail/detail/pane
tokens). `captures/imgdiff.py` reports `([0.0, 0.0, 0.0], 0.0)` for both the
A and B pairs — pixel-identical before and after.
- `adb -s emulator-5554 logcat -d` held 0 `FATAL EXCEPTION` / 0
`E AndroidRuntime` lines; `animator_duration_scale` was left at 1; no run was
started from the app.
- **APK publish.** `app-debug.apk` copied to
`~/.local/share/pipelines/data/artifacts/116/1/pipelines-debug-wip-d019213.apk`
(`d019213` = `git rev-parse --short HEAD`; the working tree is uncommitted WIP
on top of it), sha256 `e52ceb25…`. `curl -I
http://10.0.0.249:8080/artifacts/116/1/pipelines-debug-wip-d019213.apk`
returned `HTTP/1.1 200 OK`, `Content-Type:
application/vnd.android.package-archive`, `Content-Length: 17929473`, and a
streamed `GET | shasum -a 256` returned the same `e52ceb25…`.
Not verified in this pass: whether `:app:lintDebug` stays at its two
pre-existing `NewApi` errors (it was not run).
@@ -64,6 +64,7 @@ import net.awan.pipelines.ui.screens.PipelineListScreen
import net.awan.pipelines.ui.screens.RunDetailScreen
import net.awan.pipelines.ui.screens.RunHistoryScreen
import net.awan.pipelines.ui.screens.SettingsScreen
import net.awan.pipelines.ui.theme.DESTINATION_PILL_RESERVE
private data class TopDestination(val route: String, val label: String, val icon: ImageVector)
@@ -450,7 +451,3 @@ internal val DESTINATION_ITEM_SIZE = 48.dp
/** The gap between destinations, also the pill's inner padding. */
internal val DESTINATION_ITEM_GAP = 4.dp
/** Bottom space reserved for the floating destination pill, so content is never
* permanently hidden behind it (pill height + its margins + a small gap). */
private val DESTINATION_PILL_RESERVE = 88.dp
@@ -45,6 +45,8 @@ import androidx.compose.ui.graphics.vector.ImageVector
import androidx.compose.ui.semantics.Role
import androidx.compose.ui.text.style.TextOverflow
import androidx.compose.ui.unit.dp
import net.awan.pipelines.ui.theme.DETAIL_MAX_WIDTH_DP
import net.awan.pipelines.ui.theme.WIDE_RAIL_WIDTH_DP
import net.awan.pipelines.ui.theme.pipelinesText
/**
@@ -272,9 +274,3 @@ fun rememberSectionExpansion(
}
return remember(expanded) { SectionExpansionState(expanded) }
}
/** The always-visible wide section rail's width (icons with labels). */
private const val WIDE_RAIL_WIDTH_DP = 200
/** Comfortable max text width for a tab body on a wide window. */
const val DETAIL_MAX_WIDTH_DP = 840
@@ -32,26 +32,14 @@ import androidx.compose.ui.semantics.semantics
import androidx.compose.ui.unit.Dp
import androidx.compose.ui.unit.dp
import net.awan.pipelines.ui.MAX_PANE_DEPTH
import net.awan.pipelines.ui.theme.MIN_ACTIVE_PANE_WIDTH_DP
import net.awan.pipelines.ui.theme.MIN_COVERED_PANE_WIDTH_DP
import net.awan.pipelines.ui.theme.PEEK_BUDGET_DP
import net.awan.pipelines.ui.theme.PEEK_WIDTH_DP
/**
* The named dimension tokens behind the pane geometry. No screen hardcodes a
* peek width or a pane width; every offset and width is derived from these, the
* measured host width and the system insets.
*
* [PEEK_WIDTH_DP] is the minimum width of one covered pane's tappable peek.
* [PEEK_BUDGET_DP] is the fixed *total* peek budget a wide window may spend on
* all covered panes together, however deep the stack gets.
* [MIN_ACTIVE_PANE_WIDTH_DP] is the least width worth leaving to the active
* (topmost) pane before the budget has to be reduced.
* [MIN_COVERED_PANE_WIDTH_DP] is the least width a covered pane's compact
* identity needs to stay readable and tappable; when the budget cannot give
* every covered pane this much, the oldest levels are folded into one edge
* indicator instead of being squeezed below it.
*/
internal val PEEK_WIDTH_DP = 56.dp
internal val PEEK_BUDGET_DP = 224.dp
internal val MIN_ACTIVE_PANE_WIDTH_DP = 320.dp
internal val MIN_COVERED_PANE_WIDTH_DP = 112.dp
// The pane geometry tokens (peek width/budget and the minimum active/covered
// pane widths) live in ui/theme/Dimens.kt, the single source of truth for app
// geometry; this file only derives offsets and widths from them.
/**
* The one slide timing every pane shares: the [MotionStandard] token, whose
@@ -0,0 +1,83 @@
package net.awan.pipelines.ui.theme
import androidx.compose.ui.unit.dp
/**
* The app's one dimension scale: the named geometry tokens every screen, pane
* and component should measure itself against instead of writing a raw `dp` or
* `sp` literal. It is the single source of truth for app geometry, the same way
* [PipelinesTypography] is the single source of truth for type.
*
* A literal is only meant to live here or in an explicit, reasoned entry of the
* allow-list in `DimensTest`; that test scans the app's Kotlin UI sources and
* fails when a raw `dp`/`sp` literal appears elsewhere without one. Values are
* unchanged from where they were moved, so introducing this file changes no
* layout on its own.
*/
// ---- Spacing scale ---------------------------------------------------------
// Every gap and padding is meant to be a multiple of the 4dp base step below:
// the existing UI already sits on 4/8/12/16/24/32, so the scale names them once
// rather than letting each call site re-derive them.
/** Half the 4dp base step; the tightest gap the UI uses (e.g. icon/label pairs). */
internal val SPACING_XXS = 2.dp
/** One step of the shared 4dp spacing scale. */
internal val SPACING_XS = 4.dp
/** Two steps of the shared 4dp spacing scale. */
internal val SPACING_S = 8.dp
/** Three steps of the shared 4dp spacing scale; the standard inline gap. */
internal val SPACING_M = 12.dp
/** Four steps of the shared 4dp spacing scale; the standard screen/card padding. */
internal val SPACING_L = 16.dp
/** Six steps of the shared 4dp spacing scale; the standard card inset. */
internal val SPACING_XL = 24.dp
/** Eight steps of the shared 4dp spacing scale; the largest padding in the UI. */
internal val SPACING_XXL = 32.dp
// ---- Pane geometry (ui/components/SlidingPaneStack.kt) ---------------------
// The sliding pane stack derives every offset and width from these plus the
// measured host width and the system insets; no screen hardcodes a peek or pane
// width. [PEEK_WIDTH_DP] is the minimum width of one covered pane's tappable
// peek (the "collapsed strip"). [PEEK_BUDGET_DP] is the fixed *total* peek
// budget a wide window may spend on all covered panes together, however deep the
// stack gets. [MIN_ACTIVE_PANE_WIDTH_DP] is the least width worth leaving to the
// active (topmost) pane before the budget has to be reduced.
// [MIN_COVERED_PANE_WIDTH_DP] is the least width a covered pane's compact
// identity needs to stay readable and tappable; when the budget cannot give
// every covered pane this much, the oldest levels are folded into one edge
// indicator instead of being squeezed below it.
/** Minimum width of one covered pane's tappable peek (the collapsed strip). */
internal val PEEK_WIDTH_DP = 56.dp
/** Fixed total peek budget a wide window may spend on all covered panes. */
internal val PEEK_BUDGET_DP = 224.dp
/** Least width left to the active (topmost) pane before the budget is reduced. */
internal val MIN_ACTIVE_PANE_WIDTH_DP = 320.dp
/** Least width a covered pane's compact identity needs to stay usable. */
internal val MIN_COVERED_PANE_WIDTH_DP = 112.dp
// ---- Destination pill (ui/PipelinesApp.kt) ---------------------------------
/**
* Bottom space reserved by the floating destination pill, so content is never
* permanently hidden behind it (pill height + its margins + a small gap).
*/
internal val DESTINATION_PILL_RESERVE = 88.dp
// ---- Detail rail and max content width (ui/components/DetailTabs.kt) -------
/** The always-visible wide section rail's width (icons with labels). */
internal const val WIDE_RAIL_WIDTH_DP = 200
/** Comfortable max text width for a tab body on a wide window. */
const val DETAIL_MAX_WIDTH_DP = 840
@@ -2,6 +2,10 @@ package net.awan.pipelines.ui.components
import androidx.compose.ui.unit.Dp
import androidx.compose.ui.unit.dp
import net.awan.pipelines.ui.theme.MIN_ACTIVE_PANE_WIDTH_DP
import net.awan.pipelines.ui.theme.MIN_COVERED_PANE_WIDTH_DP
import net.awan.pipelines.ui.theme.PEEK_BUDGET_DP
import net.awan.pipelines.ui.theme.PEEK_WIDTH_DP
import org.junit.Assert.assertEquals
import org.junit.Assert.assertTrue
import org.junit.Test
@@ -0,0 +1,167 @@
package net.awan.pipelines.ui.theme
import java.io.File
import org.junit.Assert.assertEquals
import org.junit.Assert.assertTrue
import org.junit.Test
/**
* Guards the one source of truth for app geometry: every `dp`/`sp` literal in the
* app's Kotlin sources must either live in `ui/theme/Dimens.kt` or be an
* explicit, reasoned entry in [allowList]. The scan is source text, so it is
* fast and needs no device.
*
* The allow-list records the literals that predate the token file and that this
* item deliberately did not migrate (it must not change any layout). It is
* expected to shrink as those call sites move onto the named tokens; a literal
* that is not in it — and is not in the token file — fails the build with its
* file, line and text.
*/
class DimensTest {
/**
* Raw `dp`/`sp` literals that may still appear outside [Dimens], keyed by the
* literal text, each with the reason it is not (or not yet) a named token.
*/
private val allowList: Map<String, String> = mapOf(
// Structural / hairline values that are not design dimensions.
"0.dp" to "Structural zero: no inset, clamped-to-zero, or an empty-guard comparison.",
"2.dp" to "Progress/divider hairline strokes and 2dp icon/line gaps; half the 4dp base step.",
"3.dp" to "Tonal and border hairline (elevation/border), not a layout dimension.",
"6.dp" to "Pill shadow elevation only; not layout geometry.",
// Members of the 4dp spacing scale (see Dimens' SPACING_* tokens).
"4.dp" to "One 4dp base step (SPACING_XS): inline gap and card padding.",
"8.dp" to "Two 4dp steps (SPACING_S): standard stack/row gap and icon inset.",
"12.dp" to "Three 4dp steps (SPACING_M): standard inter-item arrangement gap.",
"16.dp" to "Four 4dp steps (SPACING_L): standard screen, card and app-bar padding.",
"24.dp" to "Six 4dp steps (SPACING_XL): empty/error padding and the 24dp progress glyph.",
"32.dp" to "Eight 4dp steps (SPACING_XXL): workflow-graph content padding.",
"10.dp" to "Dense row padding finer than the 4dp scale (10dp vertical); kept verbatim.",
// Component glyph sizes.
"14.dp" to "Status/loading icon glyph size (14dp).",
"18.dp" to "Inline icon glyph size (18dp).",
"20.dp" to "List icon glyph size and code-block inner padding (20dp).",
"48.dp" to "Minimum touch target and graph minimum visible span (48dp).",
// Workflow-graph pixel geometry (layout by design, not screen spacing).
"26.dp" to "Workflow-graph lane spacing (26dp).",
"64.dp" to "Workflow-graph terminal gap (64dp).",
"132.dp" to "Workflow-graph node width and horizontal gap (132dp).",
"260.dp" to "Collapsed workflow-graph panel minimum height (GRAPH_PANEL_MIN_HEIGHT).",
// Component container sizes.
"56.dp" to "Artifact thumbnail and graph minimum node height (coincides with PEEK_WIDTH_DP but is content size here).",
"96.dp" to "Artifact grid preferred tile edge (ARTIFACT_TILE_DP).",
"320.dp" to "Code block maximum height (CODE_BLOCK_MAX_HEIGHT).",
// Typography (sp), which is owned by Typography.kt, not the dimension file.
"11.sp" to "Workflow-graph edge-label font size.",
"12.sp" to "labelMedium/bodySmall size; Material typography role.",
"13.sp" to "Workflow-graph node-label font size.",
"14.sp" to "bodyMedium size; Material typography role.",
"15.sp" to "titleSmall size; Material typography role.",
"16.sp" to "bodyLarge/titleMedium size; Material typography role.",
"20.sp" to "Typography line height (titleSmall/bodyMedium).",
"22.sp" to "titleLarge size and titleMedium line height.",
"24.sp" to "bodyLarge line height.",
"28.sp" to "titleLarge line height.",
"0.15.sp" to "titleMedium letter spacing; a typography tweak, not a dimension.",
"0.5.sp" to "labelMedium letter spacing; a typography tweak, not a dimension.",
)
private val literal = Regex("""[0-9]+(?:\.[0-9]+)?\.(?:dp|sp)""")
@Test
fun rawDimensionLiteralsAreTokensOrReasonedAllowListEntries() {
val root = sourceRoot()
val hits = ArrayList<String>()
var scanned = 0
root.walkTopDown()
.filter { it.isFile && it.extension == "kt" }
.filter { it.relativeTo(root).path != TOKEN_FILE }
.forEach { file ->
maskCommentsAndStrings(file.readText()).lines().forEachIndexed { index, line ->
literal.findAll(line).forEach { match ->
scanned++
val text = match.value
if (text !in allowList) {
hits += "${file.relativeTo(root)}:${index + 1}: $text"
}
}
}
}
// Only the intended offenders fail; a real scan must find the allow-listed
// literals, so the regex can never pass vacuously after a refactor.
assertTrue("raw dimension literals outside ${TOKEN_FILE}: $hits", hits.isEmpty())
assertTrue("dimension scan found no literals; the matcher is broken", scanned > 0)
}
@Test
fun everyAllowListEntryHasAWrittenReason() {
val missing = allowList.filterValues { it.isBlank() }.keys
assertTrue("allow-list entries without a reason: $missing", missing.isEmpty())
assertEquals(
"allow-list keys and its reasons must have the same size",
allowList.keys.size,
allowList.values.size,
)
}
/**
* Blanks out comments and string/char literal contents while preserving line
* breaks, so a `dp`/`sp` mentioned only in prose or in a string is not a hit.
*/
private fun maskCommentsAndStrings(source: String): String {
val out = StringBuilder(source.length)
var i = 0
val n = source.length
while (i < n) {
val c = source[i]
when {
c == '/' && i + 1 < n && source[i + 1] == '/' -> {
while (i < n && source[i] != '\n') { out.append(' '); i++ }
}
c == '/' && i + 1 < n && source[i + 1] == '*' -> {
out.append(" "); i += 2
while (i < n && !(source[i] == '*' && i + 1 < n && source[i + 1] == '/')) {
out.append(if (source[i] == '\n') '\n' else ' '); i++
}
if (i < n) { out.append(" "); i += 2 }
}
c == '"' -> {
out.append(' '); i++
if (i + 1 < n && source[i] == '"' && source[i + 1] == '"') {
out.append(" "); i += 2
while (i < n && !(i + 2 < n && source[i] == '"' && source[i + 1] == '"' && source[i + 2] == '"')) {
out.append(if (source[i] == '\n') '\n' else ' '); i++
}
if (i < n) { out.append(" "); i += 3 }
} else {
while (i < n && source[i] != '"' && source[i] != '\n') {
if (source[i] == '\\' && i + 1 < n) { out.append(" "); i += 2 }
else { out.append(' '); i++ }
}
if (i < n && source[i] == '"') { out.append(' '); i++ }
}
}
else -> { out.append(c); i++ }
}
}
return out.toString()
}
private fun sourceRoot(): File {
val candidates = listOf("src/main/java", "app/src/main/java")
.map { File(System.getProperty("user.dir"), it) }
val root = candidates.firstOrNull { it.isDirectory }
assertTrue("could not locate src/main/java from ${System.getProperty("user.dir")}: $candidates", root != null)
assertTrue("no Kotlin sources found under $root", root!!.walkTopDown().any { it.extension == "kt" })
return root
}
private companion object {
const val TOKEN_FILE = "net/awan/pipelines/ui/theme/Dimens.kt"
}
}