game-ui git:20261107.2a96db7A

Immutable. This exact content never changes and is served at /api/v1/blob/81a1c91d335b5fec.

---
name: game-ui
description: amramos' ten commandments for game interfaces — intentional design for every screen, HUD, menu, line of text and font a player sees, with checks, a screen spec and a review procedure. Use whenever you design, build, change or review anything the player sees in a game (screens, HUD, menus, dialogue and other text, fonts, icons, transitions between scenes), when a game screen looks like a web page or an app, or has too much text, and when the user asks for a UI review of a screen, scene or capture.
argument-hint: "Optional: a screen, scene or capture to review"
---

# Game UI: the ten commandments

Agent-built game interfaces fail in a recognisable way: they look like a web page or an app (boxes of
equal weight, plain text spread out, no hierarchy), they explain what the screen already shows, and
their elements are there because a template had them. These ten commandments are the counter. The
reasons and sources behind each one are in the
[research page](https://github.com/amramos/game-ai-sdlc/blob/main/research/game-ui/README.md).

**The project wins.** The owner's rulings, the GDD (its pillars and interface section) and the
project's interface style sheet (usually in `docs/art/art-direction.md`) override any default here.
Where they're silent, these apply.

**Find the pillars first.** Commandment 1 judges elements against the game's pillars: read them from
the GDD or `AGENTS.md`. If the game has none, say so, recommend settling them (the first round of
`feature-planning` does), and meanwhile judge each element by the player decision it supports. This
skill only reads pillars: never write or reword them here, and never put interface rules in them;
interface rules belong in the project's interface style sheet.

## Banned looks

Some looks are such sure signs of an agent-built interface that they are banned outright. Only the
user can lift a ban, by asking for that look in their own words. "The project wins" doesn't lift
it: a GDD, a style sheet, an assumed decision, a reference game or a critic's pick never counts as
the user asking. Hands-off agents never propose a banned look, pick it or record it as assumed.
Bans cover the interface, not the world's art.

- **Dark shapes with yellow or gold borders or text.** No dark box, panel, button, badge, circle,
  square, triangle or any other shape with a yellow or gold border, outline or text. A gold coin in
  the scene is fine.

Other skills refer to this list and never restate it.

## The ten commandments

### 1. Intentional

Every box, button, word, sound, effect and omission is a decision with a reason you can name: the
pillar it serves, or the player decision it supports. A default is not a decision, and neither is
"other games have one".
- Where relevant, an element that can't be strongly linked to a pillar isn't shown. The exception is
  the functional floor every game needs: settings, pause, saving, accessibility, input help. What
  that floor must do is the housekeeping baseline
  ([housekeeping-baseline.md](../gdd-core/housekeeping-baseline.md)); how it looks is designed
  like any other screen.
- Information is given on purpose, not by default. The game knows more than the player should see:
  show what the player needs to decide and to feel, and choose what to withhold. Summaries, endings
  and results are where this slips most: whether they judge the player's choices, nudge, or only show
  consequences is a call for the pillars. A tutorial may well show verdicts; an in-world nudge (a
  character remarking on what the player missed) usually teaches better than a verdict. Before
  removing friction someone designed, find out why it's there.
- Unknown words are on purpose too. A name dropped to intrigue is fine if the game pays it off later;
  a term the player needs for a decision is taught by play before that decision, not explained in a
  caption.
- Break a rule only knowingly, for a pillar, and never at the player's expense.

*Check:* every element in the screen spec has its pillar or decision, and the spec lists what is
deliberately absent. No text tells the player what they should have done unless a pillar wants it.
Every word the player doesn't know yet is either intrigue the game pays off or taught before it's
needed.

### 2. Built from the moment

Each screen comes from what the player is doing right now, and shows what that moment needs at the
precision it needs.
- Start from the activity, not from the previous screen or a template. Keep style and interaction
  patterns consistent across screens; let layout differ.
- When the mode changes, the previous mode's live data and controls go; a dimmed, inert backdrop may
  stay for a sense of place. What matters only sometimes appears only then.
- A view that serves several moments of the loop is designed per moment: each element is shown only
  in the moments that need it, and the sketch shows each moment that looks different.
- Exact numbers where the player compares or calculates; meters or words where they should feel.

*Check:* the spec names the activity and its moments; each element names the moments it's shown in;
each number names the comparison it serves; no live data or control survives from a previous mode.

### 3. Designed with the mechanic

How the player perceives a mechanic is part of the mechanic, decided with it, not skinned on later.
- Every mechanic's plan says how the player sees it, with a sketch.
- If the interface can't show a mechanic clearly, simplify the mechanic rather than patching it with
  UI.

*Check:* a mechanic with no "how the player sees it" goes back to design.

### 4. One hierarchy, readable at a glance

- Rank everything in three reads: the objects in play, the rules that matter now, minor context.
  Push the low ranks back on purpose: darker, washed out, lower contrast.
- Ration emphasis: importance shows through brightness, size and weight, and the accent colour keeps
  the one job commandment 7 gives it. Frames, borders and titles sit mid-tone. Emphasis on everything
  is emphasis on nothing.
- About seven kinds of thing per screen at most, three to five being safer (a list counts once); no
  more than three menu levels.
- Centre for what matters, edges for what's glanced at; controls near what they act on.
- Shape before colour: roles differ in silhouette, neighbouring colours differ in brightness, and
  colour never carries meaning alone.
- Live critical state (health, a timer, a threat) uses at least two channels: a meter plus motion,
  sound or an in-world reaction. Static summaries don't need it.

*Check:* a greyscale and a blurred capture still show the key objects and their roles; a border is
never the highest-contrast thing on screen.

### 5. Grouped and composed

- Group with several cues at once: nearness, likeness, a shared panel. Panels and borders are fine;
  boxes that all weigh the same, and frames louder than their content, are not.
- A label sits beside its value; a meter beside what it measures.
- Look-alike means act-alike: the same shape or colour means the same behaviour, one icon has one
  meaning, and empty looks empty.
- What the player can act on looks actionable, unlike what they only read; a selection shows the
  control that commits it.
- One grid, consistent edges, one frame style. Centred text alone is not a menu. Align with layout,
  never with spaces.

*Check:* on the capture: label-to-value gaps, grid alignment, one frame style; two colour codes on one
screen don't reuse the same colours for different meanings unless something else (shape, icon,
placement) tells them apart; a spelling and grammar pass over every string.

### 6. Fits the hands and the full content

- Choose the layout for the input device: a stick selects by direction, a d-pad by grid, a mouse by
  nearness.
- Prompts show the player's current binding, read from the input map, never a key baked into text
  or art, so rebinding (where the baseline includes it) never leaves a prompt lying.
- Test with the full item count, never a sample. Long lists get structure (columns, tabs, a stacking
  rule) and a position indicator.

*Check:* worst-case presses or pointer travel to reach any item, at full content, on every supported
device; after rebinding an action, every prompt for it shows the new binding.

### 7. Its own identity, minimal by default

- One material kit from the game's world, on every screen from the title to the options. Borrow from
  the world or from graphic design outside games (album covers, maps, notebooks, posters), never from
  app or web UI.
- Minimal unless the genre or a pillar asks for more: a card or management game can be all interface;
  an action game shouldn't be.
- Neither more nor less decoration is the fix: toneless and flashy both fail; plain works when it's
  chosen and unmistakably the game's.
- UI colours stand apart from the world's. One accent colour has one job, named in the interface
  style sheet ("the one action", or "a consequence"), with a variant per state. When two things want
  the accent, one of them gets a shape or a weight instead.
- In-world wording for flavour actions; plain verbs where a mistake costs the player.

*Check:* beside a reference game of the same genre, does it read as a game or an app? Every accent
colour's job is listed. No banned look appears unless the user asked for it.

### 8. Show before telling

- The board reads without opening text. Character and world state show on screen, not only as
  numbers.
- Put information in the world when it lives there and stays readable; tag each element diegetic,
  non-diegetic, spatial or meta, with the reason for this game's tone.
- Never restate what the screen already shows elsewhere (a comparison row may repeat its terms). A
  label names; it doesn't explain. Highlight the words that matter.
- Show the result, and let the working play out as motion when it resolves. Spell out a formula or
  its outcomes in advance ("120 if it lands, 30 if blocked") only when the player plans with its
  parts, as in a game about building combos.
- A number sits on what it measures, never inside something else's box. Kinds that recur get an icon
  before a word: agents lean to spelling things out.
- Text-heavy play is right only when a pillar asks for it: a game about drowning in bureaucracy can
  bury the player in paperwork; an action game can't. When text belongs, give it the voice the pillars
  choose (an oracle's riddles, a song, a ledger), not a form.
- Every screen has a word budget, and low-stakes reading needs no button press.

*Check:* a fit test at native resolution over every player-facing string, at every text size the
settings offer, with no exceptions list (a long text is a writer's trim, never a wider box); a cut pass that deletes what the screen already
shows.

### 9. Alive, and fast the hundredth time

- Every press answers with a pressed state and a sound. Motion explains a change (a short slide, not
  a one-frame jump). Actions feel like what they represent.
- Repeated feedback stays short and out of the way. Nothing blocks input except the game's one
  signature moment, and that one briefly. Text that types out completes on a press; a cutscene can
  be skipped (the baseline's skip item, where it applies).
- No UI sounds yet? Synthesise them in code or use CC0 sounds, recording the source, or record them as
  owed.

*Check:* every press answered within about 0.3 s; every input block listed with its reason. Motion and
feel are judged in play or from frame sequences, never from stills.

### 10. Type with roles

- A display face for titles and the logo (expressive, read once), a body face for UI and dialogue
  (readable, fast).
- Two or three type treatments in the whole game, one text effect at a time, the same treatment for
  the same element everywhere.
- The font belongs in the game's world and is seen across the game, not in one place only.
- Legible at the smallest size it ships at: confusable glyphs tested, spacing tight enough to read
  fast, an edge or shadow on pixel text over art, columns rather than very wide lines.
- Text stays live, never baked into images, so it can be localised.
- When the fonts on hand aren't enough: with one font, the display role is a size and treatment of
  it. If a role still needs another face, search licence-safe sources: Google Fonts (all under the SIL
  Open Font License) first, other free font sites only for fonts whose licence explicitly allows
  commercial use and embedding, since many are free for personal use only. The font must cover every
  character the game's languages use and, for pixel art, have a grid at the native size. Record its
  source and licence in the credits and follow the project's rules for new assets (a hands-off run
  records the choice as assumed). If nothing fits, tell the owner what to look for: the role, the
  style, the characters, the size grid and the licence.

*Check:* text comes from the project's type roles (a theme), never a font or size set per scene; a
capture of confusable glyphs at the smallest size.

## Designing a screen

Before building a screen, write its spec from [screen-spec-template.md](screen-spec-template.md): the
player's activity and its moments, every element with its pillar or decision, its read and the
moments it's shown in, the actions and their controls, what's deliberately absent,
the word budget, the input devices and full content size, how the screen pushes things back and brings
things forward, and its motion.

- **Redesigning an existing screen? List the earlier rulings it overturns** (decisions ledgers, ADRs,
  the GDD) and settle them in the working style: ask the owner, or record each as assumed in a
  hands-off run.
- **A material layout choice gets sketches**: two or three options drawn over a real capture, side by
  side, before anyone picks (as in `feature-planning`).
- **A styled game gets a style frame first** for any new kind of screen: generated with the project's
  image tools from the worst-case content (the longest text, the most items), cleaned onto its
  palette, judged at 1:1. The build matches the frame; where the frame and the fit disagree, the fit
  wins.
- **Run the greyscale and blur checks early**, on the frame and the first build, not only at review.
- **Judge at the native resolution.** Zoomed captures are for reading detail, never for approval.

## Reviewing a screen

The procedure when asked to review a screen, scene or capture, and the one the lead and the critic use:

1. **Capture it at native resolution in its worst real state**: the longest text, the most items, the
   busiest moment. Make a greyscale and a blurred copy.
2. **List every element with its reason** (pillar or decision). An element without one is the first
   finding.
3. **Walk the checks** of all ten commandments.
4. **Rank the findings**: what makes the player miss or misread something first; identity and polish
   after.
5. **Separate mechanism from taste.** A taste call goes to the owner as a question, not into a fix.
6. **Report** at most ten findings, each as `[C<n>] <element>: <what's wrong> → <smallest fix>`, then
   one line on what stills can't show (motion, sound, feel), to be judged in play.

## Traps agent-built UI falls into

- A panel of system text for every piece of information, all at the same weight.
- A summary that tells the player what they should have done, because the data was there.
- Numbered lists, "Next" and "Skip" cards, and caption bars that restate the screen.
- Labels that explain how to use the thing they label.
- A new line of text where a visible change would do.
- A font or size chosen per scene instead of a type role.
- The previous mode's panels left on screen.
- Any of the banned looks, unless the user asked for it.