diff --git a/basemaps/flavors.md b/basemaps/flavors.md
index e725290..8723588 100644
--- a/basemaps/flavors.md
+++ b/basemaps/flavors.md
@@ -57,3 +57,28 @@ Use [ES6 spread syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/
import { namedFlavor } from "@protomaps/basemaps"
let flavor = {...namedFlavor("light"),buildings:"red"}
```
+
+## Sprites
+
+Each of the five default Flavors has an associated spritesheet. Sprites are necessary for displaying:
+
+* Townspots - circles for cities and named places at low zoom levels.
+* Highway shields - Shields are localized for different countries and road classes. See [shields](layers#shields).
+* Points of interest - used for the `light` and `dark` flavors only.
+
+Spritesheets are designed according to the [MapLibre Sprite specification](https://maplibre.org/maplibre-style-spec/sprite/). Because these sprites are stored in a static PNG image, the colors are pre-rendered to match the associated basemap Flavor.
+
+A spritesheet can be generated by building the program in [basemaps/sprites](https://github.com/protomaps/basemaps/tree/main/sprites):
+
+```sh
+cargo build # creates the binary target/release/spritegen
+make # builds all 5 default flavor spritesheets in dist/
+# Create a new JSON in flavors/custom.json and customize the colors...
+./target/release/spritegen refill.svg flavors/custom.json dist/custom
+```
+
+A custom spritesheet (`custom.json`, `custom.png`, `custom@2x.json`, `custom@2x.png`) can be referenced from a [MapLibre JSON style](maplibre):
+
+```js
+sprite: "https://example.com/assets/custom"
+```
diff --git a/basemaps/layers.md b/basemaps/layers.md
index 7267585..9c2e10f 100644
--- a/basemaps/layers.md
+++ b/basemaps/layers.md
@@ -349,18 +349,19 @@ railways and piers from OpenStreetMap. This layer represents built infrastructur
-| Key | Values | Description |
-| -------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | ----------: |
-| `kind` | See kinds below | |
-| `kind_detail` | `motorway`, `motorway_link`, `trunk`, `trunk_link`, `primary`, `primary_link`, `secondary`, `secondary_link`, `tertiary`, `tertiary_link`, `residential`, `service`, `unclassified`, `road`, `raceway`, `pedestrian`, `track`, `path`, `cycleway`, `bridleway`, `steps`, `corridor`, `sidewalk`, `crossing`, `driveway`, `parking_aisle`, `alley`, `drive-through`, `emergency_access`, `utility`, `irrigation`, `slipway`, `cable_car`, `pier`, `runway`, `taxiway`, `disused`, `funicular`, `light_rail`, `miniature`, `monorail`, `narrow_gauge`, `preserved`, `subway`, `tram` | |
-| `ref` | string | |
-| `shield_text_length` | int | |
-| `network` | string | |
-| `oneway` | string | |
-| `service` | `siding`, `crossover`, `yard` | |
-| `is_link` | boolean | |
-| `is_tunnel` | boolean | |
-| `is_bridge` | boolean | |
+| Key | Values | Description |
+| ------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | -----------------------: |
+| `kind` | See kinds below | |
+| `kind_detail` | `motorway`, `motorway_link`, `trunk`, `trunk_link`, `primary`, `primary_link`, `secondary`, `secondary_link`, `tertiary`, `tertiary_link`, `residential`, `service`, `unclassified`, `road`, `raceway`, `pedestrian`, `track`, `path`, `cycleway`, `bridleway`, `steps`, `corridor`, `sidewalk`, `crossing`, `driveway`, `parking_aisle`, `alley`, `drive-through`, `emergency_access`, `utility`, `irrigation`, `slipway`, `cable_car`, `pier`, `runway`, `taxiway`, `disused`, `funicular`, `light_rail`, `miniature`, `monorail`, `narrow_gauge`, `preserved`, `subway`, `tram` | |
+| `ref` | string | |
+| `shield_text` | string | see [shields](#shields) |
+| `network` | string | see [shields](#shields) |
+| `oneway` | string | |
+| `service` | `siding`, `crossover`, `yard` | |
+| `is_link` | boolean | |
+| `is_tunnel` | boolean | |
+| `is_bridge` | boolean | |
+
### Kinds
@@ -376,6 +377,22 @@ railways and piers from OpenStreetMap. This layer represents built infrastructur
| `rail` |
| `aeroway` |
+### Shields
+
+The `network` and `shield_text` are designed for displaying localized highway shields. The values are derived from the OpenStreetMap `ref` tag, and a spatial join with administrative boundaries.
+
+Example `network` values:
+
+| Value | Sprite | Description |
+| ----------- | :-------------------------------------------------: | ------------------------------------------------------------------------------------------------------------ |
+| `US` | | United States [Numbered Highway System](https://en.wikipedia.org/wiki/United_States_Numbered_Highway_System) |
+| `US:I` | | United States [Interstate Highway System](https://en.wikipedia.org/wiki/Interstate_Highway_System) |
+| `NL:S-road` | | Dutch S-road network |
+ |
+ |
+
+For example, an [OpenStreetMap way](https://www.openstreetmap.org/way/584348895) with the tag `ref=S100` where the way is contained within the Netherlands polygon as defined by [ideditor.codes](https://ideditor.codes) will gain the tags `network=NL:S-road`, `shield_text=S100`.
+
## transit
Lines representing scheduled passenger services suitable for rendering on the map, even at lower zoom levels. For physical infrastructure, like highways and railways, see the [roads](#roads) layer.
diff --git a/basemaps/localization.md b/basemaps/localization.md
index b271ae6..5a6c8b6 100644
--- a/basemaps/localization.md
+++ b/basemaps/localization.md
@@ -297,4 +297,3 @@ For example, to localize a map to Dutch (nl) and French (fr), one can use the fo
["coalesce", "name:nl", "name:fr"],
]
```
-