screen-locker/DESIGN_AUDIT_TODO.md

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 ElevatedButtons 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) — Cards 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.