146 lines
6.8 KiB
Markdown
146 lines
6.8 KiB
Markdown
# 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.
|