# Design audit — screen-locker Generated against safe-design-rules (anthonyhobday.com/sideprojects/saferules). Report only — nothing in this repo was changed by the audit itself. This repo has two UI surfaces, audited separately below. `~/utils/gatelock` was checked with `git -C ~/utils/gatelock rev-parse --show-toplevel` → prints `/home/kuhy/utils`, i.e. gatelock is a subdirectory of the `~/utils` monorepo, **not its own git repo**. Per audit scope, no separate gatelock report was written; see the "Shared gatelock library" section at the end instead. ## Python/Tkinter lock UI (screen_locker/) Design-token entry point check: **no `ttk.Style()` call anywhere in the package** (confirmed via repo-wide grep) and `_constants.py` holds only business-logic constants (budgets, timeouts, file paths) — zero color/font/ spacing tokens. Every color, font, and padding value is a literal typed directly at each `tk.Label`/`tk.Button`/`tk.Frame`/`tk.Entry` call site, independently, in 9 files. Evidence: - Hex color literals: **100 occurrences, 23 distinct values**, across `screen_lock.py` (6), `_ui_widgets.py` (6), `_window_setup.py` (3), `status_view.py` (21), `_heat_skip.py` (7 + 4 module-level constants), `_manual_workout_dialog.py` (15), `_manual_workout_widgets.py` (12), `_sick_dialog.py` (18), `_temperature_status_mixin.py` (5). `#1a1a1a` alone (the background) appears **31 times** — and it is *also* already defined once, correctly, as `LockConfig.bg = "#1a1a1a"` in `~/utils/gatelock/gatelock/_window.py:71`. None of the 31 in-repo literals import or reference it; `LockWindow.setup()` in gatelock applies `config.bg` to the root window (`_window.py:143`), and then every screen-locker dialog re-hardcodes the same string as if gatelock's value didn't exist. - `font=("Arial", N[, "bold"])` literals: **25 occurrences**, 6 distinct size/weight combos, e.g. `_ui_widgets.py:45,64`, `_sick_dialog.py:111,121`, `_manual_workout_widgets.py:70,89,97,116,126,137,145,164,174`. `_heat_skip.py:12-17` breaks pattern entirely with its own local `_FONT = "monospace"` constant (line 17) plus four color constants (`_BG`, `_FG_MAIN`, `_FG_SUB`, `_BTN_SKIP`, `_BTN_NO`) — the only file in the package that centralizes *anything*, and it does so locally/unshared rather than in a common module. - `padx=`/`pady=` literals: **59 occurrences**, 13 distinct values (1, 2, 5, 6, 8, 10, 12, 14, 15, 20, 28, 30) spread across 7 of the 9 files. ### Violations - **Rule 4 (everything deliberate / single source of truth)** — No `ttk.Style()`, no shared colors/fonts/spacing module. Same visual decision (e.g. background `#1a1a1a`) is independently re-typed 31 times across 9 files instead of imported once. `_heat_skip.py:12-17` even invents its own local token block, proving the pattern was known and simply not applied package-wide. Fixing any single visual value (e.g. rebranding the background) means editing up to 9 files by hand with no compiler/lint check that all sites were caught. - **Rule 1 (near-black/white, not pure)** — `bg="#1a1a1a"` (near-black, fine) is paired with pure white text: `_ui_widgets.py:38,57` default `color: str = "white"`, plus explicit `fg="white"` at `_window_setup.py:40`, `_sick_dialog.py:112,128,138` (X11 name `"white"` = `#FFFFFF`), and 6 more in `_manual_workout_widgets.py` (lines 90, 112→ label fg, 116, 137, 158, 165). Pure-white-on-near-black is the harsh contrast this rule warns against; should be a near-white (e.g. `#f0f0f0`/`#eaeaea`). - **Rule 2 (saturate your neutrals)** — `#1a1a1a` and `#2a2a2a` have equal R=G=B (26,26,26 and 42,42,42): true zero-saturation gray, not tinted warm or cool. Generic gray per the rule's definition. - **Rule 9 (distinct brightness values in a palette)** — `#ffaa00` (warning/ bonus amber, e.g. `screen_lock.py:319`, `status_view.py:181`) and `#ff8844` (network/temp-check failure, e.g. `status_view.py:121,243`, `_temperature_status_mixin.py:50,57,65`) are near-identical in hue and brightness despite signaling different states (bonus/pending vs. error/failure) — they will read as the same color at a glance. - **Rule 11 (mathematically related measurements)** — `padx`/`pady` values (1, 2, 5, 6, 8, 10, 12, 14, 15, 20, 28, 30) don't follow a consistent scale (not all multiples of 4 or 8); e.g. `pady=1` at `status_view.py:177` sits next to `pady=2` (`status_view.py:160`) and `pady=28` (`_heat_skip.py:74`) elsewhere — no discernible spacing system. - **Rule 20 (body text ≥16px)** — Multiple body-text sizes sit well under 16px: `font_size=10` at `status_view.py:248,253,255` (the last one, line 255, also uses the lowest-contrast color in the file, `#666666`, for a 10px label — compounding readability), `font_size=11` at `status_view.py:199`, `_heat_skip.py:91,104` (`font=(_FONT, 11)`), `font_size=12` at `status_view.py:160,212,225,239,243`, `_temperature_status_mixin.py:43,50,57,65`, `_sick_dialog.py:135` (`font=("Arial", 12)` on the `tk.Text` justification box), `font_size=13` at `status_view.py:121,123,181`. - **Rule 21 (line length ~70 chars)** — No widget in the package sets `wraplength` (confirmed: zero matches for `wraplength` repo-wide), so long strings render as one unbroken line regardless of window width. Concrete case: `_sick_dialog.py:205-207`, the commitment-prompt text "If you say YES and skip via 'I'm sick' tomorrow, the sick day costs 2x normal." is ~80 characters and will render as a single line at `font_size=16` with no wrap control. - **Rule 22 (button padding: horizontal ≈2x vertical)** — Only `_heat_skip.py:92,93,105,106` sets explicit button padding (`padx=14, pady=5`, ratio 2.8x — roughly compliant). Every other button in the package goes through `UIWidgetsMixin._button()` (`_ui_widgets.py:71-90`), which sets no `padx`/`pady` at all and relies on Tk's built-in default padding — a different, unspecified ratio. Button proportions are therefore inconsistent across dialogs, not a deliberate choice. - **Rule 27 (don't mix depth techniques)** — `UIWidgetsMixin._button()` (`_ui_widgets.py:71-90`) sets no `relief`, so every button in `status_view.py`, `_sick_dialog.py`, `_manual_workout_dialog.py`, and `_manual_workout_widgets.py` uses Tk's default `relief="raised"` (a faux 3D bevel). `_heat_skip.py:94,107` explicitly overrides to `relief="flat"` for its two buttons only — one dialog in the app uses a flat depth style while every other dialog uses a raised/beveled one. ### Not applicable - Rule 5 (optical alignment) — no asymmetric icon/shape glyphs requiring eye-adjusted centering; text/emoji labels only. - Rule 6 (letter-spacing/line-height by size) — Tk's `font=` tuple has no letter-spacing or line-height controls; not expressible in this stack. - Rule 7 (border contrast) — no widget in the package sets `borderwidth` or a visible border color (only one incidental `highlightthickness=0` at `_manual_workout_dialog.py:72`, which removes a border, not adds one). - Rule 8 (align with something else) — pack/grid layouts are internally consistent per-dialog; no cross-dialog layout grid to check against. - Rule 12 (order by visual weight) — button rows use uniform-weight buttons (same size/style, only color differs); no weight hierarchy to evaluate. - Rule 13 (12-column grid) — fixed 2-column form grid (`_manual_workout_widgets.py:26-49`) is a bespoke field layout, not a page grid system this rule targets. - Rule 14 (space between contrast edges, not bounding box) — cannot be verified from source without rendering; Tk widgets' effective visual edges vs. bounding boxes aren't determinable statically. - Rule 15 (closer elements lighter) — single flat z-plane throughout; no layered/stacked surfaces. - Rule 16 (shadow blur ≈ 2x offset) — no shadows anywhere in the package. - Rule 17 (simple on complex) — flat solid backgrounds behind all text; trivially compliant, nothing to flag. - Rule 18 (container brightness limits) — the one adjacent pair found, `#1a1a1a` (bg, luma 10.2%) vs. `#2a2a2a` (entry/spinbox fields, luma 16.5%), differs by ~6.3 percentage points — within the ~12% dark-mode limit. Pass. - Rule 19 (outer padding ≥ inner padding) — the lock window has no bounded "container" with edge padding (content is `place(relx=0.5, rely=0.5, anchor="center")` on a fullscreen root); the outer/inner relationship this rule assumes doesn't apply to a centered-content-on-fullscreen-canvas layout. - Rule 23 (two typefaces max) — only "Arial" and "monospace" (`_heat_skip.py:17`) appear; 2 total, within the limit (the inconsistency of *where* each is used is captured under Rule 4 above, not this rule). - Rule 24 (nest corners) — no widget sets a corner radius (stock Tk widgets are rectangular); nothing to nest. - Rule 25 (avoid adjacent hard divides) — no borders/dividers used anywhere; nothing to conflict. - Rule 26 (no shadows in dark interfaces) — Pass by omission: no shadows exist in this dark-background UI. - Rule 28 (lower icon contrast next to text) — emoji glyphs (💪, 😷, ✓, ☀, ⚠, 🔥) share the same `fg=` color as their surrounding text; Tk offers no per-glyph opacity control within one Label's text, so this can't be addressed without moving emoji into separate, independently-colored widgets. ### Notes - The absence of any shared theme/constants module means every rule above that *did* pass (18, 26) did so incidentally, not by design — there's no guard rail keeping it that way as new dialogs get added. - `_heat_skip.py`'s local `_BG`/`_FG_MAIN`/`_FG_SUB`/`_BTN_SKIP`/`_BTN_NO`/ `_FONT` constants are the one place in the package that already knows centralizing tokens is worth doing — promoting this pattern to a shared `screen_locker/_theme.py` (or, better, sourcing from gatelock's `LockConfig`) would fix Rule 4 and cascade-fix several of the violations above in one pass. ## Flutter app (stronglift_replacement/workout_app/) Design-token entry point: `lib/main.dart:68-74` declares `ThemeData(colorScheme: ColorScheme.fromSeed(seedColor: Colors.indigo, brightness: Brightness.dark), useMaterial3: true)` — a real Material 3 seed theme exists. However, **`Theme.of(context)` / `colorScheme` is referenced zero times anywhere in `lib/screens/` or `lib/widgets/`** (confirmed via repo-wide grep). The theme is declared but never consumed — every one of the 24 .dart files under `lib/` hardcodes colors directly instead. - `Colors.*` literals: **~210 occurrences** across `screens/` and `widgets/`, 27 distinct named colors. Most common: `Colors.white` (98×), `Colors.grey.shade800` (18×), `Colors.redAccent` (12×), `Colors.greenAccent` (11×), `Colors.grey.shade900` (10×). - Raw hex `Color(0xFF...)` literals bypassing `Colors.*` entirely: `manual_workout_screen.dart:173,201` (`Color(0xFFFF4444)`) and `manual_workout_screen.dart:238,246` (`Color(0xFF88CCFF)`) — these are the **exact same hex values** independently hardcoded on the Python/Tkinter side (`#ff4444` and `#88ccff`, see e.g. `_sick_dialog.py:70`, `_manual_workout_dialog.py:58`), coincidentally kept in sync only because no one has touched either yet. - `fontSize:`/`fontWeight:` literals: 72 occurrences; `history_screen.dart` alone uses 12 distinct font sizes (9, 11, 12, 13, 14, 15, 16, 17, 18, 20, 22, 26). ### Violations - **Rule 4 (everything deliberate / single source of truth)** — `main.dart` builds a `ColorScheme.fromSeed`, but it is dead code from a theming standpoint: no screen or widget reads it. Every screen re-derives its own ad hoc dark palette from `Colors.grey.shade900/800/700` plus assorted accent colors, so a single rebrand (e.g. changing the seed color) would require manually editing all 24 files instead of one. - **Rule 1 (near-black/white, not pure)** — `Colors.white` (pure `#FFFFFF`) used 98 times for primary text/icons, e.g. `home_screen.dart:113,122,128, 211,248,267`, `settings_screen.dart:231,278,430`, `history_screen.dart:209,410`. `Colors.black` also appears at `rep_circle.dart:76` (`Colors.black87`, near-pure) as text-on-white in the neutral rep-circle state. None of these are the theme's actual near-white/near-black — they're Flutter's pure-value constants. - **Rule 2 (saturate your neutrals)** — `Colors.grey.shade900/800/700/400` are Material's standard zero-saturation grays (equal R=G=B), used as the entire background/surface system in place of `colorScheme.surface` (which, being seeded from indigo, *would* be saturated). Bypassing the theme produces exactly the generic-gray outcome the theme was set up to avoid. - **Rule 9 (distinct brightness values)** — `Colors.redAccent` (errors) and `Colors.orangeAccent`/`Colors.orange.shade800` (pending/resume state) are both used as status-signal colors of similar brightness in adjacent UI (e.g. `home_screen.dart:222` orangeAccent for active-session text next to `Colors.greenAccent` for success at line 200 — three status colors of comparable weight competing in one card). - **Rule 18 (container brightness limits, dark ≤~12%)** — The repeated `Scaffold(backgroundColor: Colors.grey.shade900)` / `AppBar(backgroundColor: Colors.grey.shade800)` pairing (Material `shade900`=`#212121`, luma 12.9%; `shade800`=`#424242`, luma 25.9% — a ~13-point jump) appears in every screen's `Scaffold`/`AppBar`: `home_screen.dart:104,106`, `settings_screen.dart:275,277`, `history_screen.dart:206,208`, `workout_screen.dart:495,498`, `manual_workout_screen.dart:154,156`. This exceeds the ~12% dark-interface guideline every time it's used. - **Rule 20 (body text ≥16px)** — Extensive small body text below 16px: `fontSize: 9` at `history_screen.dart:612`, `fontSize: 11` (11 occurrences, e.g. `home_screen.dart:311`, `history_screen.dart:333,486,612`, `settings_screen.dart:388`), `fontSize: 12` (14 occurrences), `fontSize: 13` (7 occurrences) — well under the 16px minimum for supporting/secondary text throughout. - **Rule 22 (button padding: horizontal ≈2x vertical)** — `home_screen.dart: 242` and `:261` set `padding: const EdgeInsets.symmetric(vertical: 14)` on full-width `ElevatedButton`s with no `horizontal:` argument, which defaults `horizontal` to `0.0` — the inverse of "horizontal ≈2x vertical". - **Rule 26 (no shadows in dark interfaces)** — The app declares `brightness: Brightness.dark` (`main.dart:71`), yet `rep_circle.dart: 105-111` adds an explicit `BoxShadow(color: Colors.black26, blurRadius: 4, offset: Offset(0, 2))` to the rep-tracking circle — the one shadow in the whole app, in a UI this rule says shouldn't have any. ### Not applicable - Rule 5 (optical alignment) — standard Material icons/widgets are already optically centered by the framework; no custom asymmetric glyphs. - Rule 6 (letter-spacing/line-height by size) — the only `letterSpacing` uses found (`home_screen.dart:311` → 1.1, `history_screen.dart:333` → 1.3, `settings_screen.dart:388` → 1.4) are all on the same small `fontSize: 11` eyebrow-label text, consistently given positive tracking as the rule recommends for small text — no counter-example at larger sizes to check against, so marked N/A rather than a forced Pass. - Rule 7 (border contrast) — `Border.all(color: color.withValues(alpha: 0.4))` (`settings_screen.dart:491`) derives border color from the same status color as the fill, by design (a tinted pill), not a container-edge border this rule targets. - Rule 8 (align with something else) — standard `Column`/`Row`/`ListView` layouts; no cross-screen alignment grid to check. - Rule 12 (order by visual weight) — screens are single-column flows (cards stacked top-to-bottom); no left/right or center/edge weight arrangement to evaluate. - Rule 13 (12-column grid) — mobile single-column layouts throughout; no multi-column grid system in use. - Rule 14 (space between contrast edges) — cannot be verified statically without rendering the widget tree. - Rule 15 (closer elements lighter) — `Card`s at `shade800` sit on `shade900` backgrounds (lighter-on-darker as they "lift"), which is directionally correct, but see Rule 18 above for the magnitude issue. - Rule 17 (simple on complex) — flat-colored cards/containers throughout; nothing complex to conflict with. - Rule 19 (outer padding ≥ inner padding) — spot-checked `home_screen.dart:143` (`EdgeInsets.all(24)` outer) vs. its nested `_WorkoutCard` internal padding (`EdgeInsets.all(16)`, `home_screen.dart:188`) — outer ≥ inner, consistent with the rule; not exhaustively checked across all 24 files. - Rule 21 (line length ~70 chars) — Flutter `Text` wraps by default at widget width; no unbounded-line risk equivalent to the Tk surface. - Rule 23 (two typefaces max) — no custom `fontFamily` set anywhere; the whole app uses the Material/system default typeface. Trivially compliant. - Rule 24 (nest corners) — `BorderRadius.circular(8)` is reused verbatim across unrelated containers (`home_screen.dart:301`, `calendar_widget.dart:63`, `history_screen.dart:402,643,705,772`, `settings_screen.dart:490,548,587`) but none of these visibly nest inside another rounded container in the surrounding code, so there's no outer/inner radius relationship to check. - Rule 25 (avoid adjacent hard divides) — only one `Divider` found (`exercise_tile.dart:115`), not adjacent to another border/divide. - Rule 27 (don't mix depth techniques) — the app consistently uses flat `Container`/`Card` fills with no shadow except the single instance flagged under Rule 26; effectively one depth style (none) throughout, so no mixing to flag. - Rule 28 (lower icon contrast next to text) — icons consistently use `Colors.white54`/`Colors.white38`/`Colors.white70` (already lower-contrast than adjacent full-white/near-white text) rather than full `Colors.white`, e.g. `exercise_tile.dart:150,160,167,177,248,252`, `history_screen.dart:331,486,507` — this one is actually already followed reasonably consistently. Pass. ### Notes - Rule 4 is the dominant finding for this surface too: an unused `ColorScheme.fromSeed` plus ~210 ad hoc `Colors.*`/`Color(0x...)` literals means every other color/contrast rule (1, 2, 9, 18) is failing as a direct consequence of the same root cause, not independently. Routing all 24 files through `Theme.of(context).colorScheme` (or a small shared `AppColors`/`AppTextStyles` class) would be the highest-leverage single fix. - The coincidental hex overlap between `Color(0xFFFF4444)`/`Color(0xFF88CCFF)` (Flutter) and `#ff4444`/`#88ccff` (Python/Tkinter) shows the two UI surfaces are visually related by convention only — there is no shared token file either could import from, on either language side. ## Shared gatelock library `~/utils/gatelock` is **not** its own git repo — `git -C ~/utils/gatelock rev-parse --show-toplevel` resolves to `/home/kuhy/utils`, so it's a subdirectory of the `~/utils` monorepo. Per audit scope, gatelock itself was not walked against all 28 rules and no separate `~/utils/gatelock/DESIGN_AUDIT_TODO.md` was written. What's relevant here: gatelock defines exactly **one** real design token — `LockConfig.bg: str = "#1a1a1a"` (`~/utils/gatelock/gatelock/_window.py:71`), applied via `self.root.configure(bg=self._config.bg, ...)` in `LockWindow.setup()` (`_window.py:143`). Both consumer repos re-hardcode this same literal instead of reading it back off their own `LockConfig` instance: - **screen-locker** (this repo) — `#1a1a1a` appears 31 times across 9 files (see the Tkinter section above) despite `screen_lock.py:148-153` constructing a `LockConfig` instance (as `config`) just a few lines above each of those files' widget-creation call sites. - **diet-guard** — not inspected as part of this audit (out of scope for this repo's report), but per the shared-infra note in the task, it is the other known consumer of `LockConfig`/`LockWindow` and should be checked for the same duplication pattern if/when a design audit is run there. Fixing the screen-locker Rule 4 finding above by having widget-creation code read `self._lock_config.bg` (threaded through from the `LockConfig` already built in `ScreenLocker.__init__`) instead of re-typing `"#1a1a1a"` would close this loop without needing any gatelock-side change.