Docs: Notes on adding an icon library

ICONS.md

@@ -36,3 +36,9 @@ For presets, it is possible to define an icon via the `imageURL` property in add
 `imageURL` is extensively used to specify the logos of brand presets by the [name-suggestion-index](https://github.com/osmlab/name-suggestion-index) project.
 
 It must not be used for regular preset entries in [iD tagging schema](https://github.com/openstreetmap/id-tagging-schema).
+
+## For maintainers: adding a whole new icon *source*
+
+Introducing a new prefixed family (e.g. a new public icon set with its own npm repo or CDN) touches **schema-builder**, **id-tagging-schema**, **iD**, and often **other editors**. That process is documented on a separate page so this file stays short for contributors:
+
+**[Adding a new icon source](docs/Adding-a-new-icon-source.md)** — JSON schema impact, Taginfo URLs, iD sprites, StreetComplete’s Gradle icon task, GoMap!! assets, and a checklist.

docs/Adding-a-new-icon-source.md

@@ -0,0 +1,60 @@
+# Adding a new icon source (maintainers)
+
+This document describes what has to happen when the tagging schema adopts icons from a **new family** (a new string prefix). The latest addition in practice was **`roentgen-`** ([Röntgen](https://github.com/enzet/map-machine#r%C3%B6ntgen-icon-set) icons; see also [`ICONS.md`](../ICONS.md)). It complements the contributor-facing overview there.
+
+## Is this a breaking change to the JSON schema?
+
+**No**, we do not consider a new icon prefix a breaking schema change.
+
+In [`schemas/preset.json`](../schemas/preset.json), `icon` is a free-form string, so values such as `roentgen-ford` need no schema update.
+
+Apps and libraries should fall back when an icon is unknown or missing (e.g. generic glyph or text only); with that in place, new prefixes should not break integrations; the experience is simply weaker until explicit support exists.
+
+## End-to-end flow
+
+1. **Choose a prefix** (e.g. `roentgen-`) and ensure **stable public SVG URLs** (GitHub raw, npm package, etc.).
+2. **id-tagging-schema**: use `"icon": "prefix-name"` in presets, categories, or field `icons`.
+3. **schema-builder**: document the source; add Taginfo `icon_url` mapping in `lib/build.js`; release `@ideditor/schema-builder`.
+4. **id-tagging-schema**: bump the schema-builder devDependency and rebuild.
+5. **Each editor / consumer** that renders preset icons: extend its own resolution or bundling (see below).
+
+## 1. id-tagging-schema
+
+| What | Details |
+|------|---------|
+| Data | [`data/presets/**/*.json`](https://github.com/openstreetmap/id-tagging-schema/tree/main/data/presets), categories, fields—set `icon` / `icons` to the new prefixed id. |
+| Build | `npm run build` uses `@ideditor/schema-builder`; after a schema-builder release, bump its version in `package.json`. |
+
+No SVG packages are added here; only strings in JSON.
+
+## 2. schema-builder (this repo)
+
+| File | Change |
+|------|--------|
+| [`ICONS.md`](../ICONS.md) | Add a bullet under “Where do the icons come from?” with link, prefix, and short description. |
+| [`lib/build.js`](../lib/build.js) | In `generateTaginfo`, add an `else if` for the new prefix so Taginfo preset items get a correct `icon_url` (same idea as `maki-`, `temaki-`, `fas-`, `iD-`). **Note:** `roentgen-` is used in presets but was historically missing from some paths—new families should not repeat that gap. |
+| Tests | Optional: extend `tests/schema-builder.test.js` with a fixture icon to assert Taginfo output. |
+
+## 3. iD
+
+iD shows preset icons from **SVG symbol sprites** built at release time and shipped with the app.
+
+| Area | Action |
+|------|--------|
+| `package.json` | Add npm dependency if the set is published, **or** vendor SVGs under e.g. `svg/…`. |
+| `dist:svg:…` | New `svg-sprite` script, same pattern as `dist:svg:maki` / `dist:svg:temaki`. |
+| `modules/svg/defs.js` | Register the new sprite sheet id. |
+| `modules/ui/preset_icon.js` | Only if the set needs special sizing/styling (e.g. Röntgen). |
+| `dist/img/*-sprite.svg` | Generated by the sprite build. |
+
+[Rapid](https://github.com/facebook/Rapid) follows the same sprite approach where it mirrors iD.
+
+## 4. StreetComplete
+
+Uses a **Gradle** task: [`DownloadAndConvertPresetIconsTask`](https://github.com/streetcomplete/StreetComplete/blob/master/buildSrc/src/main/java/DownloadAndConvertPresetIconsTask.kt). It collects all `icon` values from `presets.json`, then maps each **prefix** to GitHub raw SVG URLs. Unknown prefixes are **skipped** (no Android drawable, no `presetIconIndex` entry).
+
+**StreetComplete maintainers** need to extend `getDownloadUrls` with another prefix branch and URL template, then re-run the preset-icon Gradle task so drawables are regenerated. The task downloads **one HTTP URL per icon** and expects each glyph as its **own `.svg` file** on the server—usually a **flat folder** of files (e.g. `…/icons/{name}.svg`), matching how Maki, Temaki, and Röntgen publish icons. Sets that ship only bundled sprites or irregular layouts need a different pipeline or preprocessing before this task can use them.
+
+## 5. Other tools
+
+Other tools that use the icons – like GoMap!! – have similar scripts to download and process the required icons.