# 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 visible reduced-motion toggle is required in player mode. It must suppress non-essential animation without changing gameplay feedback or authority. - 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. - A visible mute toggle is required in player mode. It disables local sound and vibration feedback only; it must never change protocol behavior. ## 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 touch devices, movement uses an always-visible circular joystick at least 160 by 160 CSS pixels. Its drag stays within the control, returns to center on release, cancellation, pause, disconnect, and browser blur, and sends only cardinal movement intentions. - The joystick has a dead zone and directional hysteresis. Its locally scheduled repeat interval is bounded and never faster than the server's movement cooldown. Touch swipes remain supported. Phones do not show a directional-button cluster. - 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. - The player identity is represented by a distinct character shape, not `P1` or `P2`. Object, blocked-move, pause, and result feedback must pair a shape or icon with its color. - 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. - Compute cell size from the current server projection and available map area. At the minimum supported phone viewport a common 7 by 7 projection must use at least 46 CSS-pixel cells, while smaller projections may grow to 72 pixels. Do not alter, retain, or infer hidden maze cells to fill spare space. - 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. - At `412 x 916`, the map is the dominant visual region; controls overlay it instead of creating an empty lower region. Status remains icon-first and readable without requiring reading as the normal interaction path. - 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 `32 x 32` 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. ## 12. Pre-reader onboarding and usability - On a player's first active projection, show an eight-step, wordless-first walkthrough for joystick drag and release, walls, key, vision, compass, exit, and meeting the other player. Each step uses a large icon; short Russian text is secondary support for an adult. - The walkthrough provides a replay button and an explicit Russian skip button for adults. It is browser-local UI only and never changes server state. - A child must be able to distinguish their character, the other character, key, vision, compass, exit, blocked movement, and results through at least two channels such as shape/icon, position, motion, outline, color, sound, or haptic feedback. - Before release, record a representative pre-reader observation using `docs/PRE_READER_USABILITY.md`, or record a project-owner-approved deviation with its reason and impact.