map

When to use

• The story is geographic. Reach for a map only when WHERE is the point — coverage areas, jurisdictions, service territories, where the grants or pilots landed. If the geography is incidental and the comparison is really between named things, a progress or stats row reads faster than a basemap.
• Choropleth for magnitude, highlight for membership. Use the default choropleth when each region carries a number and the audience needs the gradient — how much, where. Use highlight when the named regions are a set (the eight pilot states, the four regions we serve) and there is no magnitude to rank.
• Name regions any common way. Country names resolve by full name, ISO code, or common alias (Brazil / BR / Burma→Myanmar); on map us, by full name, postal code, or abbreviation (California / CA / Calif.). A name the basemap can't bind is reported as a muted ‘?’ row in the legend and stamped on the figure — fix the spelling, don't ignore the gap.

When not to use

• A map as decoration. If the regions aren't the comparison — you just want a US-shaped graphic behind some numbers — drop the basemap. An image scrim or a stats row carries headline figures without implying the geography is the message.
• Too many shades to read. A choropleth past a dozen distinct values asks the eye to rank colors it can't separate. Bucket the values, switch to highlight for a categorical read, or lead with a progress ranking and keep the map as support.
• Sub-region precision the basemap doesn't have. The basemaps draw US states and world countries — not counties, districts, sub-national regions, or city pins, and the world cut (110m) omits the smallest city-states. If the story lives below that line, a labeled image of the real map serves better than forcing it onto the basemap.

Common mistakes

• Assuming an unresolved region name is silently dropped. An unmatched region name isn't silently dropped or fatal — it surfaces as a muted '?' row in the legend and is stamped on the figure, AND npm run lint:deck flags it explicitly (an unknown-map-region warning naming the region). Fix the spelling; the lint output tells you which name didn't resolve.
• Using highlight with numeric-looking trailing values, expecting a color ramp. Under highlight, the trailing value is just an optional legend LABEL, not a magnitude — it doesn't drive a color ramp the way it does under the default choropleth; a numeric string there is treated as a category label, not a number.

Authoring

<!-- _class: map -->

## Where the program runs.

- Kenya `4.2`
- Nigeria `3.1`
- India `2.8`
- Brazil `2.2`

Slots

Data shape

• Region names resolve by full name, ISO/postal code, or common alias — the resolver accepts any mix, but picking one convention per chart keeps the legend readable.
• Choropleth values must share one consistent unit/scale across all regions — the ramp maps low→high over the full authored range, so mixing e.g. raw counts and percentages skews the gradient.

Variant decision rule

• world — The story spans multiple countries — program reach, service territories, grants — the default basemap, spelled out.
• us — The story is entirely within the United States — swaps to the US-states basemap with insets.
• highlight — The regions are a SET, not a ranked magnitude — membership matters (pilot states, regions served), not a gradient of values.
• robinson — A more familiar, traditional-atlas world silhouette fits the deck's visual tone better than the default. Note this trades away area accuracy: Equal Earth (the default) is area-preserving by construction, so robinson is a LESS area-faithful compromise projection, not a more faithful one — pick it for the recognizable shape, not for improved area accuracy.
• grouped — Whole blocs, continents, or categories should fill as one unit (European Union, ASEAN) rather than spelling out every member country.

Variants

<!-- _class: map us -->

## us swaps in the US-states basemap.

- California `48.2`
- Texas `36.4`
- New York `31.0`
- Florida `27.5`
- Illinois `19.3`
- Ohio `14.1`
- Georgia `11.8`
- Washington `9.6`

<!-- _class: map world -->

## The same engine, pinned to the world basemap.

- Germany `42.7`
- Japan `35.1`
- Canada `28.9`
- Australia `21.4`
- Chile `16.2`
- Morocco `12.8`
- Vietnam `10.5`
- Iceland `7.3`

<!-- _class: map highlight -->

## highlight fills by category, not value.

- Kenya `East Africa`
- Nigeria `West Africa`
- India `South Asia`
- Brazil `Latin America`

<!-- _class: map robinson -->

## robinson swaps the projection.

- United States `42`
- Brazil `31`
- Nigeria `27`
- Kenya `24`
- India `38`
- Indonesia `19`
- Germany `22`
- Australia `12`

<!-- _class: map highlight grouped -->

## grouped fills whole blocs at once.

- European Union `Tier 1`
- ASEAN `Tier 1`
- Sub-Saharan Africa `Tier 2`
- Latin America `Tier 2`

Related

• progressthe regions are really a ranking — labeled bars compare magnitudes faster than shades
• statsa few headline figures with no geography to place them on
• piechartregional shares of a single whole rather than a value per place
• imagethe geography needs detail (counties, cities, routes) the basemap can't draw