docs(ui): define web application visual style requirements

AGENTS.md

@@ -12,8 +12,10 @@ This directory is a local mirror of the ChatGPT project “maze32”.
 ### Language
 
 - Write all canonical documentation in English.
-- Write source comments, test names, protocol identifiers, log messages, and
-  user-facing diagnostic text in English.
+- Write source comments, test names, protocol identifiers, and system log
+  messages in English.
+- Write all player-facing browser UI copy, game messages, and user-visible
+  browser errors in Russian.
 
 ### Canonical documents
 
@@ -22,6 +24,8 @@ This directory is a local mirror of the ChatGPT project “maze32”.
 - `PLANS.md` defines the current implementation milestone and its evidence.
 - `docs/BOARD_PASSPORT.md` defines confirmed hardware facts and explicit
   unknowns.
+- `docs/UI_STYLE.md` defines the canonical browser visual language, responsive
+  layout, controls, and presentation behavior.
 - Files under `sources/` remain read-only references and are never canonical
   implementation files.
 

ARCHITECTURE.md

@@ -320,6 +320,17 @@ drop-key action. The UI renders only server-provided visible state. The observer
 view supports fitting, panning, or zooming the complete `128 x 64` map without
 changing server authority.
 
+`docs/UI_STYLE.md` is the canonical browser presentation contract. The player
+layout supports a minimum `412 x 916` CSS-pixel viewport. Observer mode requires
+at least `1024 x 768` CSS pixels and presents a large-screen requirement message
+below that threshold. Responsive layout changes presentation only; they never
+change projection content, command validation, or server authority.
+
+All application assets are local and precompressed. Browser startup and play
+must not depend on internet access, third-party CSS, remote fonts, icons,
+analytics, or content services. The complete compressed web payload is limited
+to 1.5 MiB within the unchanged 1,984 KiB LittleFS partition.
+
 A temporary session token is stored in browser-local storage so page refresh
 can reattach to the existing slot. It is not a permanent account credential and
 does not need to survive an ESP reboot.

MVP.md

@@ -215,7 +215,34 @@ Browser controls must support:
 - If the player does not reconnect within 60 seconds, the match ends in a draw.
 - Reloading a page is treated as a reconnect, not as leaving the match.
 
-## 11. Technical constraints
+## 11. Browser presentation
+
+- The browser UI uses one dark, humorous retro arcade visual language across
+  provisioning, lobby, player, and observer modes, as defined in
+  `docs/UI_STYLE.md`.
+- All player-facing UI copy, game messages, and browser errors are in Russian.
+- The UI uses a near-black background, purple panels, turquoise interactive
+  accents, blue for Player 1, pink for Player 2, and plant-like green maze
+  walls. Important state is distinguished by icons, labels, outlines, or
+  shapes in addition to color.
+- The player map consumes all space not required by fixed status and control
+  panels. The player view supports a minimum `412 x 916` CSS-pixel viewport
+  without page scrolling.
+- Computers support keyboard movement and on-screen arcade controls. Tablets
+  support swipes and on-screen controls. Phones use directional swipes without
+  on-screen directional buttons.
+- An always-visible `OK` control with a key icon drops the carried key without
+  confirmation and exposes the Russian accessible label `Сбросить ключ`.
+- Observer mode requires at least a `1024 x 768` CSS-pixel viewport, initially
+  fits the complete map, and supports zoom and pan. Smaller viewports show a
+  Russian large-screen requirement message.
+- Sound and vibration are enabled by default after the first user interaction
+  when the browser and device support them.
+- The application has no runtime internet dependency. It uses local assets,
+  locally authored SVG icons, plain CSS, and a system monospace font styled to
+  resemble a pixel font.
+
+## 12. Technical constraints
 
 - Target: ESP32-C6FH4, 4 MB Flash, no required PSRAM.
 - Build: PlatformIO, `espressif32@7.0.1`, ESP-IDF, compatible
@@ -224,6 +251,8 @@ Browser controls must support:
   MVP.
 - Static browser assets reside in LittleFS and should be compressed for the
   production image.
+- The complete compressed web payload must not exceed 1.5 MiB and must fit the
+  unchanged 1,984 KiB LittleFS partition.
 - HTTP serves the application and provisioning pages; WebSocket carries live
   lobby, control, and match messages.
 - The initial LwIP socket limit is 16.
@@ -232,7 +261,7 @@ Browser controls must support:
 - Active lobby and match state may live in RAM and need not survive an ESP
   reboot. Wi-Fi settings must survive reboot.
 
-## 12. MVP acceptance criteria
+## 13. MVP acceptance criteria
 
 The MVP is accepted when all of the following are demonstrated on the target
 board:
@@ -263,8 +292,12 @@ board:
     60-second reconnect timeout ends it as a draw.
 12. A representative match normally completes in approximately five minutes
     after balance tuning, without imposing a hard match timer.
+13. The Russian retro arcade UI follows `docs/UI_STYLE.md`, works at the
+    required player and observer viewport sizes in the current stable Chrome,
+    Safari, Firefox, and Edge releases, requires no runtime internet access,
+    and stays within the 1.5 MiB compressed web-asset budget.
 
-## 13. Explicitly outside MVP
+## 14. Explicitly outside MVP
 
 - More than two active players or more than one concurrent match.
 - More than four observers.
@@ -277,4 +310,3 @@ board:
 - Persistent match recovery after ESP reboot.
 - OTA firmware partitions and OTA update flow.
 - Dependence on PSRAM, an unverified LED, or an assumed board pinout.
-

PLANS.md

@@ -23,8 +23,10 @@
     not yet available. Expected evidence may be listed in advance.
 11. If later work invalidates recorded evidence, reopen the affected milestone
    and change its status before continuing.
-12. All project documentation, milestone text, source comments, test names, and
-   user-facing diagnostic messages are written in English.
+12. All project documentation, milestone text, source comments, test names,
+    protocol identifiers, and system log messages are written in English.
+    Player-facing browser UI copy, game messages, and browser errors are
+    written in Russian.
 
 ## Milestone 001 — Requirements and technical baseline
 
@@ -397,15 +399,20 @@ into the browser.
 ### Scope
 
 - Name selection, lobby, countdown, running, paused, and result screens.
+- Dark, humorous retro arcade presentation following `docs/UI_STYLE.md`.
+- Russian player-facing copy and locally served pixel-styled graphics.
 - Maze viewport and visual landmarks.
-- Keyboard movement and touchscreen swipes.
+- Keyboard movement, touchscreen swipes, and responsive on-screen arcade
+  controls.
 - Accessible drop-key action.
 - Inventory, vision duration, compass hint, connection, and error feedback.
+- Default sound, supported-device vibration, and animated game feedback.
 - Session restoration after page refresh.
 
 ### Deliverables
 
 - Responsive browser application and compressed production assets.
+- Implemented visual tokens, SVG icon set, and shared control styles.
 - Browser interaction tests for desktop and mobile input.
 - Accessibility and viewport behavior checks.
 
@@ -416,7 +423,17 @@ into the browser.
 3. Hidden and previously seen cells are not retained on screen.
 4. Inventory, effects, hints, pause, and results are unambiguous.
 5. Refresh restores the active player without changing position or inventory.
-6. The production asset image fits its LittleFS partition.
+6. The player flow remains usable without page scrolling at a `412 x 916`
+   CSS-pixel viewport and at representative tablet and desktop viewports.
+7. Player-facing UI copy and browser errors are in Russian while protocol and
+   system-log text remain in English.
+8. The application requires no runtime internet access or third-party UI
+   dependency.
+9. The complete compressed web payload is no larger than 1.5 MiB and fits the
+   unchanged LittleFS partition.
+10. The current stable Chrome, Safari, Firefox, and Edge releases pass the
+    applicable browser interaction checks, with versions and test date
+    recorded in the milestone evidence.
 
 ### Evidence
 
@@ -436,6 +453,7 @@ and reconnect behavior.
 ### Scope
 
 - Full-map observer rendering with player and object updates.
+- Large-screen observer layout with initial full-map fit, zoom, and pan.
 - Observer access without a password and strict read-only authorization.
 - Player disconnect detection and authoritative pause.
 - Session reattachment and 60-second monotonic deadline.
@@ -455,6 +473,8 @@ and reconnect behavior.
 4. Reconnection within 60 seconds restores and resumes the same state.
 5. Reconnection timeout ends the match in a draw.
 6. Observer attempts to send mutation commands are rejected and audited.
+7. Observer mode works at `1024 x 768` CSS pixels and larger, while smaller
+   viewports show the required Russian large-screen message.
 
 ### Evidence
 

docs/UI_STYLE.md

@@ -0,0 +1,145 @@
+# Browser UI style
+
+## 1. Purpose
+
+This document defines the canonical visual language, controls, responsive
+layout, and presentation behavior for every maze32 browser mode. Product rules
+remain in `MVP.md`, and browser authority boundaries remain in
+`ARCHITECTURE.md`.
+
+## 2. Visual direction and tone
+
+- Use a dark retro arcade-game style throughout network provisioning, name
+  selection, lobby, player, and observer modes.
+- Use humorous copy, imagery, animation, object names, and suggested player
+  names wherever the game remains clear and usable.
+- Humor must be understandable to children, non-offensive, and based on
+  internet humor that is current when the release is designed. Runtime access
+  to external meme or content services is forbidden.
+- Use only a dark theme. A light theme is outside the MVP.
+- Use small SVG icons, pixel-art graphics, or graphics styled to resemble
+  pixel art. Locally authored icons must not require an external icon library.
+- Use a system monospace font stack with CSS pixel-style treatment. The UI must
+  not download Google Fonts or any other external font at runtime.
+
+## 3. Color system
+
+The exact color values may be tuned during implementation, but their semantic
+roles must remain stable:
+
+- black or near-black for the application and map background;
+- purple for panels and elevated surfaces;
+- turquoise for interactive accents;
+- blue for Player 1 and pink for Player 2 across every screen, map object, and
+  message;
+- green for success, yellow for warnings, red for errors, blue for pause, and
+  orange for disconnection;
+- green vegetation, bushes, and plants for maze walls.
+
+When two semantic roles use related colors, icons, labels, outlines, or shapes
+must keep them unambiguous. Important player and object information must not be
+communicated by color alone. Key objects use an additional label, outline, or
+marker.
+
+WCAG AA contrast certification and dedicated color-vision-deficiency palettes
+are not MVP requirements.
+
+## 4. Animation, sound, and haptics
+
+- Use frequent but purposeful animation for screen transitions, movement,
+  pickups, game events, and humorous feedback.
+- Pending controls blink until their command is resolved.
+- A reduced-motion mode is not required for the MVP.
+- Sound and vibration are enabled by default. They begin only after the first
+  user interaction when required by the browser, and are used only when the
+  browser and device support them.
+- Dedicated sound and vibration toggles are not required for the MVP.
+
+## 5. Shared controls
+
+- Controls use a retro arcade appearance with clear normal, hover, pressed,
+  disabled, and pending states.
+- Visible keyboard-focus outlines are not required for the MVP.
+- On computers, movement works from the keyboard and from an on-screen
+  directional control cluster fixed in the lower-right corner.
+- On tablets, an on-screen directional control cluster is fixed in the
+  lower-right corner for right-handed use. Touch swipes remain supported.
+- On phones, movement uses directional swipes and no on-screen directional
+  buttons are shown.
+- The always-visible key-drop control is labelled `OK`, includes a key icon,
+  and is positioned closer to the upper edge of the screen than the
+  directional controls. Dropping does not require confirmation.
+- The key-drop control has the Russian accessible label `Сбросить ключ`.
+
+## 6. Shared layout
+
+- The map fills all viewport space not required by fixed status and control
+  panels. The player match screen must not require page scrolling.
+- A fixed status panel occupies the top of the screen.
+- The persistent player status shows the player name, carried key when one is
+  held, active vision effect, and match state.
+- Connection details and the Wi-Fi settings link belong in a secondary panel,
+  not in the persistent status row.
+- Countdown, pause, and result states appear as modal overlays above the map.
+- Errors and rejected actions appear as contextual tooltips or notices near
+  the relevant control or status area.
+- The lobby uses separate blocks for players, observers, and match actions.
+- Network provisioning uses the same colors, type, controls, and humor as the
+  game application.
+
+## 7. Player map presentation
+
+- Keep the player near the center of the map viewport except where maze
+  boundaries prevent it.
+- Render unknown space as a solid background. Never infer, retain, animate, or
+  decorate maze geometry outside the server-provided visible projection.
+- Use a nominal cell size of 20 CSS pixels on phones and 40 CSS pixels on
+  tablets and computers. Minor adjustment is allowed to fit browser chrome and
+  safe areas without making the map unusable.
+- Player zoom and pan controls are not part of the MVP.
+- Use different colors plus labels, outlines, shapes, or icons to distinguish
+  player ownership and object types.
+- Give immediate visual feedback when movement is rejected by a wall without
+  revealing hidden state.
+
+## 8. Responsive behavior
+
+- The minimum supported player viewport is `412 x 916` CSS pixels.
+- Support both portrait and landscape orientations. Suggest landscape when it
+  materially improves play, but do not block portrait play.
+- Respect display safe areas and keep essential status and controls visible.
+- Scale icons and controls up on tablets and computers while preserving map
+  priority and fixed panel placement.
+- Validate the MVP against the current stable releases of Chrome, Safari,
+  Firefox, and Edge available at the time of validation. Record the tested
+  browser versions and date; legacy browser support is outside the MVP.
+
+## 9. Observer presentation
+
+- Observer mode is supported only at viewports of at least `1024 x 768` CSS
+  pixels. Smaller viewports show a Russian message explaining that a larger
+  screen is required.
+- Place player and match status blocks above the full maze.
+- Initially fit the complete `128 x 64` map into the available map area.
+- Provide zoom and pan without granting any gameplay control or changing
+  server authority.
+
+## 10. Asset and dependency budget
+
+- Use plain project CSS without a third-party CSS framework.
+- All runtime web assets must be served locally from the ESP. The UI must not
+  require internet access, remote fonts, external icons, analytics, or content
+  services.
+- Precompress production web assets. Their complete compressed payload must
+  not exceed 1.5 MiB and must fit the existing 1,984 KiB LittleFS partition.
+- The LittleFS partition size and Flash layout remain unchanged.
+
+## 11. Visual verification
+
+- Verify player layout at the minimum `412 x 916` viewport and representative
+  tablet and desktop viewports.
+- Verify observer layout at `1024 x 768` and at a larger desktop viewport.
+- Verify every control state, modal state, responsive transition, Russian
+  message, and semantic color role manually and through focused browser tests
+  where practical.
+- Golden-image or screenshot-regression tests are not required for the MVP.