From 2cfbc32715584ea00d6b894696d8c5070dbd20e8 Mon Sep 17 00:00:00 2001 From: funman300 Date: Wed, 29 Apr 2026 21:59:38 +0000 Subject: [PATCH] docs: add UI-first design principle MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every player-triggered action (new game, undo, draw, pause, open any overlay, switch mode, etc.) must be reachable from a visible UI control. Keyboard shortcuts are optional accelerators only — never the sole entry point. New gameplay features ship with the UI control alongside the system that backs it. - ARCHITECTURE.md §1 (Design Principles): add UI-first bullet. - ARCHITECTURE.md §5 plugin table: rename "Key" column to "Shortcut" and add a note that the column lists optional accelerators, not primary entry points. - CLAUDE.md (Bevy Conventions): add a matching hard rule. Surfaced during smoke testing: the N+N "press again to confirm" toast collides with the ConfirmNewGameScreen modal because the keyboard flow is the only entry point. Adding a visible New Game button (next commit) makes the modal the single source of truth for the confirm flow. Co-Authored-By: Claude Opus 4.7 (1M context) --- ARCHITECTURE.md | 5 ++++- CLAUDE.md | 1 + 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index fab0eb1..a6460e5 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -51,6 +51,7 @@ Solitaire Quest is a cross-platform Klondike Solitaire game written in Rust, tar - **No panics in game logic.** Every state transition returns `Result<_, MoveError>`. Panics are only acceptable in startup/configuration code. - **One language, one repo.** The game client, sync client, shared types, and sync server are all Rust crates in a single Cargo workspace. - **Plugin-based Bevy architecture.** Each major feature is a Bevy `Plugin`. Systems are small and single-purpose. Cross-system communication uses Bevy `Event`s. +- **UI-first interaction.** Every player-triggered action — new game, undo, draw, pause, open stats / settings / help / profile / leaderboard, etc. — must be reachable from a visible UI control. Keyboard shortcuts exist only as optional accelerators for power users; they are never the sole entry point. A player using only mouse or touch must be able to perform every action. New gameplay features ship with the UI control alongside the system that backs it. --- @@ -235,7 +236,9 @@ Done ### Bevy Plugins -| Plugin | Key | Responsibility | +The "Shortcut" column lists optional keyboard accelerators. Every action in this table must also be reachable from a visible UI control (button, menu item, on-screen affordance) per the UI-first design principle in §1; the shortcut is a power-user convenience, not the sole entry point. + +| Plugin | Shortcut | Responsibility | |---|---|---| | `CardPlugin` | — | Card entity spawning, sprite management, drag-and-drop | | `TablePlugin` | — | Pile markers, background, layout calculation | diff --git a/CLAUDE.md b/CLAUDE.md index 775498e..a5ffc6d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -77,6 +77,7 @@ cargo clippy -p solitaire_core -- -D warnings - Resources own shared state. Events communicate between systems. Components own per-entity data. - All UI screens are built with Bevy UI (`bevy::ui`). Never mix UI layout and game logic in the same system. - Layout is recomputed on `WindowResized` — never assume a fixed window size. +- **UI-first.** Every player-triggered action (new game, undo, draw, pause, open stats / settings / help / profile / leaderboard, switch mode, etc.) must be reachable from a visible UI control. Keyboard shortcuts are optional accelerators — never the sole entry point. New gameplay features ship with the UI control alongside the system that backs it; do not merge a feature that is keyboard-only. ---