BGA Studio Guidelines

BGA Studio Guidelines (UX/UI)

This page covers UX guidelines for games on Board Game Arena. Read the official PDF or bga.li/mRdx first. This page is an unofficial summary.

Goal: most games should be instantly playable on any device — desktop at midnight or phone at lunch.

Use this page to validate UX before switching your game from ALPHA → BETA → RELEASE.

A — Layouts

A.1 Layout arrangement

Game should fit a square ratio and show everything the active player needs. Use vertical scroll for secondary info (other players' progress, secondary boards).

✔️ Do

• Center the play area on all devices.
• Leave a "no action" margin around the board (deselect, scroll on mobile).
• Use HTML anchors to jump between distant sections.
• Use spacers / transparent whiteblocks to group pieces clearly.
• Keep score, turn order, and objectives accessible (button/tab/panel), not always visible.
• Tuck rare abilities into tooltips.

❌ Don't

• Do not hide game components behind popups — you should see everything you'd see on a real table.
• Do not place "always accessible" info permanently on the player panels.
• Do not add in-game logos or branding that isn't part of the actual game.
• Do not scatter related info (e.g. resources) across three corners.

Note: Layout mantra: Central = shared actions. Top/Bottom = global info. Panels = private resources.

A.2 Action Bar

The Action Bar always shows the current state: turn in progress, who we're waiting for, or what the player can do.

✔️ Do

• Center main awaited actions (Play card, End turn, Confirm move).
• Place secondary/greyed-out actions next to them.
• Put cancel / undo / remove on the right, visually separated from forward actions.
• Use the Action Bar for: actions targeting another player, Pass/End turn/time-related actions, auction phases, and small resource exchanges without dedicated board space.
• Keep it to max 4 buttons + context so it doesn't overflow on mobile.

❌ Don't

• Do not replace board-component actions with Action Bar buttons — players should act on the board like in real life.
• Do not stick custom buttons next to BGA's built-in buttons (replay controls, etc.).
• Do not let cancel actions visually compete with main actions.
• Do not show "Round in progress" text inside the bar — display it on the table or as flavor text of the current action.

Example: Wingspan shows the current round as flavor text under the action bar.

→ See C.3 for button colors.

A.3 Player panels

Player panels let anyone glance at: who's playing, color, score, turn order, and resources gained.

✔️ Do

• Keep panels compact — a 4-player game on mobile must not occupy more than ¼ of the screen.
• Offer HTML anchor shortcuts to jump to a player's main components.

❌ Don't

• Do not put settings, titles, round numbers, or other redundant info in panels.
• Do not put always-accessible info (score, objectives) only on player panels.

A.4 Popups

✔️ Do

• Reserve automatic popups for tutorials only.
• Make any required popup skippable on click/touch/timer.
• Use the game wiki for rules, hints, scoring tips, helpers.

❌ Don't

• Do not block game flow with popups (forbidden).
• Do not use popups mid-game — only allowed for between-round/stage scoring.

Example: area around popup clickable - should be used to close it

→ See B.1 for non-blocking alternatives.

A.5 Clarity & Zoom

Use vertical space and good layout instead of zoom controls.

✔️ Do

• Design so the core game is fully playable at 100% scale.
• Trust browser zoom: Ctrl+wheel on desktop, pinch on mobile.

❌ Don't

• Do not add zoom buttons unless absolutely necessary (large secondary boards, very text-heavy cards like Ticket to Ride).

If you must add zoom buttons:

• + (plus): zoom in
• – (minus): zoom out
• 🏠 Home: reset to default

B — Usability

B.1 Tooltips

Tooltips add insight, not duplication.

✔️ Do

• Add extra detail beyond what's on screen (translatable text, hints about when to use).
• Use them to zoom into small text/icons on large game boards.
• Close tooltips when the user taps away on mobile.

❌ Don't

• Do not show the same info twice the same way.
• Do not add a tooltip that's just a zoomed-in copy of an already-visible card — that's a sign your components are mis-sized.

Example: Ticket to Ride hover tooltips name cards/decks without distraction.

Example: Altered shows minimal default info, with full detail on hover.

B.2 Forbidden actions

✔️ Do

• Grey out / disable actions that exist but aren't currently available.

❌ Don't

• Do not show disabled buttons for actions that are never relevant in the current context — just hide them.

B.3 Undo, Reset, Restart

BGA philosophy: fast, fluid, intuitive. Use these controls sparingly.

✔️ Do

• Use Confirm buttons for impactful, irreversible actions (end turn, discard, commit resources).
• Prefer timed confirmation (5–8s) over undo.
• Offer one Restart Turn for the whole turn when rules allow, not per-micro-action undo.
• Allow "Undo last move" only when a turn has more than 2 actions.

❌ Don't

• Do not add an Undo button for every action — multiplies validation steps, slows the game.
• Do not layer Undo on top of Reset on top of Confirm — over-validation.
• Do not use Undo to paper over misclicks — fix the layout instead (bigger targets, clearer highlights).

C — Design

C.1 Typography & translations

Clarity beats style.

✔️ Do

• Use the default BGA font.
• Use clean sans-serif if you must change.
• Maintain good line spacing.
• Make all text translatable via BGA's translation system.
• Support LTR and RTL languages — test alignment & mirroring.
• Ensure your font supports accents/diacritics (é, ñ, ü).
• Meet WCAG AA contrast.
• Test on a phone — what's readable on a 27" monitor may not be on mobile.

❌ Don't

• Do not use decorative or themed fonts (hard to read, licensing risk, missing glyphs).
• Do not mix multiple fonts for "theme."
• Do not embed text directly into images without alt-text.

C.2 Highlights & Glowing auras

Players should never wonder "what do I click?"

✔️ Do

• Highlight valid options so the awaited action is obvious.
• Show consequences visually before the player commits.

Example of highlighting valid options on the table.

C.3 Button colors and styling

Button colors are a shared language across BGA. Mandatory for consistency.

Color	Meaning	statusBar.addActionButton
🔵 Blue	Advance, confirm, move forward	primary
🔴 Red	Cancel, undo, stop, exit	alert
⚪ White / Transparent	Optional/side actions	secondary
⚫ Grey	Disabled, completed, unavailable	(disabled state of any of the above)

✔️ Do

• Display usernames in their assigned player color.
• Outline player-color text so it stays visible (e.g. yellow on white).
• Test player colors on both light and dark backgrounds.
• Take any extra colors from game components (cards, tiles, tokens), not UI buttons.

❌ Don't

• Do not reassign blue/red/grey for game-specific meaning.
• Do not tint UI buttons to match the game's theme.

Note: Think of button colors as traffic lights: blue = go, red = stop, grey = unavailable.

C.4 Sizing & responsiveness

✔️ Do

• Keep the main play area centered on every device.
• Use fluid layouts that expand/contract to fit available space.
• Leave margins around the board (prevents mobile misclicks).
• On desktop/tablet: show the entire board when possible.
• On mobile (vertical): stack secondary elements below the main action zone.
• Make everything readable and usable at 100% scale.
• Add HTML anchors / jump-links for vertical layouts.

❌ Don't

• Do not use fixed-width designs.
• Do not rely on zoom for legibility.
• Do not let layout break when players zoom in/out.
• Do not make any interactive element smaller than 32×32px (see E.3).

Reference implementation: bga-jump-to demo

C.5 Background & extras

The background is the table surface your game sits on.

✔️ Do

• Use thematic, modern backgrounds (subtle playmat look).
• Add slight texture or pattern.
• Apply a touch of blur so components remain the visual focus.
• Prioritize contrast against the game's components.

❌ Don't

• Do not use pure flat colors.
• Do not use sharp, busy, detailed backgrounds that compete with the game.
• Do not let the background reduce component visibility.

D — Feedback

D.1 Errors & invalid actions

Silence is never acceptable. Every failed action must say why.

✔️ Do

• Use a short shake, grey-out, or tooltip on failure.
• Show concise plain-text errors: "You don't have enough resources."
• Pair color with icons or text (don't rely on red alone).

❌ Don't

• Do not leave the player guessing.
• Do not use color alone — colorblind users won't see it.

D.2 Game Logs

Logs are the narration of the match. Critical for asynchronous games.

✔️ Do

• Log every major action: card plays, moves, resource changes, eliminations.
• Always say who acted and what changed.
• Use icons, colors, formatting for fast scanning.
• Provide alt-text for graphic components inside logs.
• Group small simultaneous actions into a one-liner.
• Log automated/forced actions too.

❌ Don't

• Do not write walls of text or use oversized images that break log flow.
• Do not hide who did the action.

Good:

• "Marianna placed [red tile] on [central board] (+2 points)."
• "Alex drew 2 [train cards]."

Bad:

• "+2 points"
• "Card drawn"

D.3 Animation

Animations explain what moved, where it went, why it matters.

✔️ Do

• Use animations for: cards entering a hand, tokens moving, score count-up.
• Keep regular animations at 0.5s, max 0.8s.
• Batch repetitive updates (don't show 50 tiny +1 animations).

❌ Don't

• Do not animate trivial updates one by one.
• Do not use looping, bouncing, or glowing animations as decoration.

→ See BGA animation library.

D.4 Sound effects

Sound is a bonus, not a requirement.

✔️ Do

• Keep volume below the BGA default.
• Keep sounds short, sharp, purposeful.
• Always pair sound with a visual cue.

❌ Don't

• Do not add long looping soundtracks.
• Do not let any action be communicated by sound only.
• Do not surprise players with loud audio.

E — Accessibility

E.1 Design for all

✔️ Do

• Pair colors with icons, textures, or shapes.
• Meet contrast ratio 4.5:1 minimum.
• Label every button, icon, and interactive element (screen readers).
• Use bold shapes, clear outlines, strong contrast to differentiate pieces.

❌ Don't

• Do not rely on color alone.
• Do not use flashing or rapidly alternating visuals.
• Do not depend on fine details or subtle shading to differentiate components.

E.2 Colorblind-safe design

✔️ Do

• Add unique shapes/symbols/outlines per pawn or token color.
• Place small icons in card corners (or patterns) so suits are recognizable without hue.
• Meet WCAG AA for text and icons.
• Outline player-color names so yellow doesn't vanish on white.

❌ Don't

• Do not assume players perceive color differences.

E.3 Tap targets

✔️ Do

• Minimum 32×32px for any interactive element.
• Aim for 40–44px (greatly reduces mis-taps).
• Leave spacing between buttons, tokens, cards.
• Group many options into expandable menus or secondary panels.
• When space runs out, add scrolling — don't shrink components.

❌ Don't

• Do not cram small icons into tight clusters.
• Do not shrink components below the minimum to fit.

E.4 Settings & customization

✔️ Do

• Put all game settings in BGA's standard settings menu.
• Reuse existing BGA controls.
• Offer per-game options only where relevant: animation speed, tooltip detail, sound on/off.

❌ Don't

• Do not build custom settings UI (the platform is phasing those out).
• Do not duplicate controls already available globally.

F — Technical

F.1 Endgame & Replays

✔️ Do

• Make replays flow without interruption.
• Keep animations skippable and playable at minimum speed.
• Keep logs and highlights in sync with each replayed action.
• Match the scoring pay-off to game length — long games deserve a longer reveal.
• Use synchronous notifications per scoring step and this.displayScoring for points animations.

❌ Don't

• Do not put blocking popups in replays.
• Do not drop the final score instantly at the end of a long game.

F.2 Refresh & Continuity

A refresh should feel invisible.

✔️ Do

• Restore the exact game state after refresh (no missing/corrupted info).
• Restore temporary UI: whose turn it is, pending actions, selected components.
• Treat the server as the source of truth for all critical state.
• Expect disconnect/reconnect as normal — BGA may do it at any time.

❌ Don't

• Do not store critical state in client-only memory.
• Do not rely on session continuity hacks.

F.3 Error handling

✔️ Do

• Handle disconnects and dropped actions without breaking flow.
• Show players short, friendly messages explaining what went wrong.
• Log precise error details to the developer console.
• Isolate the error to the affected action.

❌ Don't

• Do not crash the game on invalid input.
• Do not expose raw server logs or stack traces to players.
• Do not block the whole table because of one failed request.

Pre-release Checklist

Version 1.0.0 — May 22, 2026

#	Check
1	Layout centers and scales on all devices.
2	Action Bar ≤ 4 buttons, never replaces components.
3	Tooltips: clear, translatable, useful.
4	Buttons follow BGA standards (blue = forward, red = cancel).
5	No blocking popups mid-game.
6	Animations: quick, smooth, informative.
7	All tap/click targets ≥ 32px.
8	Colorblind-safe icons in place.
9	Endgame shows breakdown + replay option.
10	Game state restores cleanly after refresh.

Closing thoughts

• Alpha: gather usability feedback.
• Beta: listen to the crowd — confusion spots = redesign spots.
• Iterate: small UX tweaks = big retention gains.
• Watch metrics: if players stall at a phase, that's your design flag.

Play other BGA games with similar mechanics — get inspired, challenge your assumptions, and treat UX as a key part of design, not an afterthought.

BGA Studio Guidelines (Source Code)

Make your code as easy to read and understand as possible: clearly named functions and variables, comments when necessary, ...

Everything should be in english in your code.

In case you drop the support for a project, another developer should be able to follow up on your code and understand it easily.

Front (JS) code

Generated code

Generated code (SCSS, Typescript) is tolerated, as long as you provide both source files and built files, ideally with build tools. The build file should not be minimized, as someone taking over your project might not know the source language, and will the work on the built file ignoring the source file. Build tools are useful if he wants to continue the project with your source files.

JS and CSS files remains the used file in the end, BGA does not handle natively other languages.

Templates

Use of .tpl file and view.php is deprecated and forbidden for new projects.

Back (PHP) code

Game name and option names should be Capitalized.

Framework functions

Undocumented functions

Do not use undocumented functions. They may change or be deleted without warning, and your game will not work anymore. Any change on documented function will be avoided as much as possible, and will be notified.

Function override

Do not override framework functions. Use a wrapper instead.

Bad :

public function getPlayerNameById($player_id) { // same name as the framework function = override
  if ($player_id == 0) {
    return 'Automata';
  } else {
    return parent::getPlayerNameById($player_id);
  } 
}

Better :

public function myGameGetPlayerNameById($player_id) { // // different name = wrapper
  if ($player_id == 0) {
    return 'Automata';
  } else {
    return $this->getPlayerNameById($player_id);
  } 
}

State functions

States functions should be prefixed "st"

Args functions should be prefixed "arg"

Action functions should be prefixed "act"

Namespacing

The classes should be namespaced following the PSR-4 norm. That means you won't need to require the classes, as BGA will be able to autoload them.

So a class named PowerCardManager on a PowerCard folder should have the filename <mygame>/PowerCard/PowerCardManager.php and start like this :

<?php
declare(strict_types=1);
namespace Bga\Games\<mygame>\PowerCard;
class PowerCardManager {

Other

.action.php shouldn’t be used anymore, auto-wiring should be used instead.

The actions function must check any input. To avoid code duplication, they can use the arg function.

Example :  

$args = $this->argPlayCards();
if (!in_array($cardId, $args['selectableCardsIds'])) { throw new \BgaUserException(...); }

Don’t use `@` to ignore the errors of a function call.