# Icons / art — design brief

A working document for a session on replacing the placeholder **"dummy icon"**
SVGs with real art.

---

## 1. Shared project context (read this first)

*Battle for 'Tismo* is an HTML5 port of a turn-of-the-millennium strategy game.
Pure JavaScript, no build step, no runtime dependencies.

- **Server-authoritative**, but art is purely client-side: SVGs live in
  `client/assets/` and are referenced by filename from `shared/data/*.js`
  (`icon: "icon_<name>.svg"`) and a few `client/assets/` references in JS.
- **No build step and no image pipeline** — dropping an `.svg` in
  `client/assets/` and referencing its filename is the whole process. The
  `nix/package.nix` `web` output copies `client/` and `shared/` verbatim.
- **Data** lives in `shared/data/` (barrel: `shared/data.js`).

### Commands

- Install once: `npm install`.
- One suite: `node tests/run_tests.js --file <name>.js`. **Never the full suite**
  during development — the commit hook runs it.
- Server + client: `node server/server.js --port 27015 --bind 127.0.0.1`.

### Conventions

- A missing icon gets a dummy SVG reading `dummy icon - <name>` (the standing
  rule in `AGENTS.md`/`ROADMAP.md`).
- **Visual changes are reviewed by eye before commit.** For icons, build a small
  standalone HTML gallery that links `client/css/style.css` and shows the icons
  at the sizes the UI actually uses, then **open it in Firefox**
  (`firefox <path>`). Do not screenshot and do not just print the path.
- 2-space indent for `.js`; no new libraries.
- Commit only when asked; one imperative sentence; the hook runs the full suite.

---

## 2. Requirement (from `ROADMAP.md`)

> Real art for the placeholder "dummy icon" SVGs.

The roadmap names a specific set of files, but most of those have since been
drawn; **re-derive the live list** with the command below before starting.

---

## 3. Current placeholders

Find them with:

```sh
rg -il "dummy" client/assets/*.svg
```

As of this writing that lists (subject to change):

- `icon_computer.svg`, `icon_human.svg` — player-list control icons (diplomacy
  tab; used at 20px).
- `icon_geothermal_plant.svg`, `icon_offshore_wind_turbines.svg` — power plants.
- `icon_icbm.svg`, `icon_missile.svg` — missiles.
- `icon_submarine.svg` — the submarine.
- `icon_uranium_enrichment.svg` — the nuclear building.
- `icon_space_launch_center.svg` — the spy-satellite building.

`icon_spy.svg` and the roadside `icon_radar.svg`, `icon_coastal_cannon.svg`,
`icon_chip_foundry.svg`, `icon_wind_turbines.svg` have already been drawn.

The dummy template (all of them share it):

```svg
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" style="height:512px;width:512px">
  <rect x="8" y="8" width="496" height="496" rx="24" fill="#2b3550" stroke="#ffffff" stroke-width="12"/>
  <text x="256" y="266" fill="#ffffff" font-family="sans-serif" font-size="40" font-weight="700" text-anchor="middle">dummy icon</text>
  <text x="256" y="316" fill="#ffffff" font-family="sans-serif" font-size="40" font-weight="700" text-anchor="middle">spy</text>
</svg>
```

---

## 4. Art direction

- **Canvas:** `viewBox="0 0 512 512"`, square. Keep the `style="height:512px;width:512px"`
  attribute the other assets use.
- **Reads small.** Icons render at roughly **20-34 px** — `.stack-type-icon` 22,
  `.stack-unit-icon` 26, `.bt-top .building-icon` 34, `.row-card .building-icon`
  34, `.control-icon` 20, `.value .value-icon` 13. A single strong silhouette
  beats detail; avoid thin strokes, fine text and tiny gradients.
- **Flat, high-contrast vector** in the game's palette (see the existing icons
  for the house style, e.g. `icon_battleship.svg`, `icon_jet_fighter.svg`,
  `icon_modern_infantry.svg`). A dark plate behind the subject helps it read on
  the map and in the panel, as the dummy does.
- **No text** in real icons. Transparent or plate background, consistent with
  neighbours.
- **Specifics to capture:** a nuclear trefoil for the enrichment centre; a
  country silhouette / masked figure for the spy; a fish-like hull for the
  submarine; a rocket with fins for the missile and an intercontinental variant
  for the ICBM; a globe/bust for human vs. a monitor/chip for computer; a
  geyser for geothermal; an offshore turbine on its platform vs. an onshore
  turbine.

---

## 5. Workflow per icon

1. Draw the SVG (any editor; keep it hand-editable, no embedded bitmaps).
2. Save as `client/assets/icon_<name>.svg` — **same filename**, so no data file
   change is needed. If a filename must change, update the `icon` field in the
   matching `shared/data/*.js` entry (units, buildings, resources, improvements,
   technologies, ...).
3. Build a small gallery HTML (below) linking `client/css/style.css`, showing
   every changed icon at the real sizes, on the real backgrounds.
4. Open it in Firefox and show the user; only commit once approved.
5. Run `node tests/run_tests.js --file data_test.js` (it asserts some icons are
   `.svg`) and any suite that references the icon.

### Gallery skeleton

```html
<!doctype html><meta charset="utf-8">
<link rel="stylesheet" href="file:///home/adrien/strategy-game/client/css/style.css">
<body style="background:#05070c;color:#e8eef7;font:14px sans-serif;padding:24px">
  <h1>Sizes: 20 / 22 / 26 / 34 px</h1>
  <div style="display:flex;gap:24px;align-items:flex-end">
    <!-- per icon: <img src="file:///home/.../client/assets/icon_x.svg" style="width:34px"> etc. -->
  </div>
</body>
```

---

## 6. Tests to add / extend

- `tests/data_test.js` already checks a few `icon` fields end in `.svg` and are
  non-empty; extend it to cover the newly drawn assets (units, buildings,
  resources) so a missing/renamed file is caught.
- No pixel tests — icons are reviewed by eye, per the workflow above.

---

## 7. Gotchas

- **The filename is the contract.** Most data entries reference the file by
  string; renaming without editing the data leaves a broken `<img>` that only
  shows in the browser, not in tests.
- **Case and path.** Assets are served from the repo root as `/client/...`;
  `client/js` references them as `assets/icon_x.svg` relative to the page. Keep
  lowercase `snake_case` filenames.
- **Small-size legibility** is the acceptance test, not how good it looks at
  512px. Zoom the gallery down to 20px before judging.
- **Nix packaging** copies the tree, so no manifest needs updating — but a new
  file must be committed for the deployed build to include it.
- A serving cache may hide a replaced file; hard-reload when checking in-game.

---

## 8. Relevant files

- `client/assets/` — all icons (this is where art goes).
- `shared/data/units.js`, `buildings.js`, `resources.js`, `improvements.js`,
  `technologies.js` — the `icon:` references.
- `client/css/style.css` — icon display sizes.
- `client/index.html` — where icons appear in the HUD/modals.
- `tests/data_test.js` — icon sanity checks.

## 9. Related design docs

`SIMPLIFICATIONS.md` (repo root).