From 61cae665de6a019ae50c0e91ab712733f64d726b Mon Sep 17 00:00:00 2001 From: "Tobias (FMC)" Date: Wed, 18 Mar 2026 03:33:03 +0100 Subject: [PATCH] Docs: Notes on adding an icon library --- ICONS.md | 6 ++++ docs/Adding-a-new-icon-source.md | 60 ++++++++++++++++++++++++++++++++ 2 files changed, 66 insertions(+) create mode 100644 docs/Adding-a-new-icon-source.md diff --git a/ICONS.md b/ICONS.md index 9baa527..1dbd766 100644 --- a/ICONS.md +++ b/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. diff --git a/docs/Adding-a-new-icon-source.md b/docs/Adding-a-new-icon-source.md new file mode 100644 index 0000000..a454305 --- /dev/null +++ b/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.