From 34a0627e763750d05f5e5cce8987e5d7346cf082 Mon Sep 17 00:00:00 2001 From: phg Date: Sun, 8 Mar 2026 11:52:24 +0100 Subject: [PATCH] Enhance documentation for UI consistency and field widget layout in README, SPEC, and TASKS --- README.md | 2 +- SPEC.md | 10 ++++++++++ TASKS.md | 7 +++++++ 3 files changed, 18 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 043747c..3a987f3 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ - Write tests before implementation - Prefer small PR-sized tasks - Keep business logic out of widgets where possible +- Field-like widgets should default to compact 3-row controls with no empty spacer line between the value row and the border - Every screen must have empty/loading/error coverage - Every interactive feature needs at least one Pilot test - Visual changes should be covered by snapshot tests - diff --git a/SPEC.md b/SPEC.md index 41b110a..23e5e78 100644 --- a/SPEC.md +++ b/SPEC.md @@ -21,6 +21,14 @@ Default: The PAM realm will be selected by default, but users can choose other r Users will be able to create VMs by selecting from predefined templates. The script will handle the necessary API calls to create and configure the VM based on user input. +#### UI consistency + +Field-like widgets should follow the compact Textual widget-gallery pattern used for single-line controls. + +- Most field-like widgets should be 3 rows high by default. +- There must be no blank spacer line between the field content area and the surrounding border. +- Taller controls are only acceptable when a widget is intentionally multi-line or requires additional vertical content. + #### General This screen will show the general configuration options for the VM, such as: @@ -202,7 +210,9 @@ The script will include error handling to manage API errors, authentication fail The script will be tested using Textual interaction tests with run_test() and Pilot. Business logic will be kept in a central module, and testing will include running pytest, ruff check .., and ruff format .. . Add snapshot coverage for default, loading, and error states. +For form-heavy screens, use snapshot coverage and visual review to confirm that single-line field widgets render as compact 3-row controls and do not show an empty spacer line inside the border. ### Documentation The script will be well-documented, summarizing changes and any unresolved UX concerns. +Document any intentional deviation from the compact 3-row field-widget layout or the no-inner-spacer rule as an explicit UX choice. diff --git a/TASKS.md b/TASKS.md index fc6abdc..7b07c83 100644 --- a/TASKS.md +++ b/TASKS.md @@ -11,6 +11,7 @@ Use these rules for every implementation task in this repository: - Use `ruff` for linting and formatting. - Prefer small vertical slices that can be implemented and verified independently. - Keep Proxmox API and business logic out of Textual widgets where possible. +- Field-like widgets should use compact 3-row layouts by default; bordered fields must not include an empty inner spacer row between the content and the border. - Every screen must have explicit default, loading, success, empty, and error states where applicable. - Every interactive screen must be covered by Textual interaction tests using `run_test()` and `Pilot`. - Important visual states should be covered by snapshot tests. @@ -26,6 +27,12 @@ Codex should use these commands: - Run lint checks: `uv run ruff check .` - Format code: `uv run ruff format .` +## Shared visual validation + +- Use snapshot tests and visual review for form-heavy screens to confirm that single-line field widgets stay 3 rows high by default. +- Verify that bordered field-like controls do not render an empty spacer line above or below the value row. +- Allow taller controls only when a widget is intentionally multi-line or needs additional vertical content, and call that out in the task summary as a UX choice. + ## Implementation backlog ### Task 1: Bootstrap the Textual app and project structure