Map colours and the accent

The most common styling ask — "our map in our brand colours" — is one call to the Styling Foundations module over Map Maker's ten Foundations colours, and an eleventh, the accent, carries the theme to the routes, areas and pins drawn on top.

Map colours: setMapColors()

Partial objects are fine; an unknown name throws an Error, a value that is not a colour a RangeError:

import { StylingFoundationsModule } from '@tomtom-org/maps-sdk/map';

const styling = await StylingFoundationsModule.get(map);
styling.setMapColors({ land: '#f3f5f7', water: '#accbe2', roadMajor: '#a1b8ce', label: '#364659' });

The ten are Map Maker's own, under its names and in its order, so a colour you set here is the one you set on the same control in Map Maker's Foundations. mapColorNames lists them with accent last, baseMapColorNames (typed BaseMapColorName) lists the ten alone, in the same order, to build a base-map colour picker from, and MapColors types the object setMapColors takes. What each reaches:

How one name fans out:

• Every layer and shade the style built from it. roadMajor recolours the motorway line, the trunk line one shade lighter, their darker outlines, the tunnel and bridge variants and the small-scale version — each re-derived from your colour by the same HSL offset the style used, so the shade relationships survive rather than a flat fill. The offsets are measured off the loaded style, not shipped as a table, so the mechanism follows the style to its next version.
• Tints of their own hue — a hospital's pink, a campus's cream, a shopping area's yellow — keep that hue and follow artificial's lightness, with their saturation scaling with its luminance the way the style's theme derives them. A dark built-up colour darkens and mutes them too, a grey included.
• On the mono styles, from land. monoLight and monoDark derive the other nine from land with their theme's own formulas, so land alone recolours the whole map; a colour you set outright still wins, and a road you set carries its outline and major class with it. The other styles set all ten and derive nothing.

await map.setStyle('monoLight');
styling.setMapColors({ land: 'hsl(38, 36%, 93%)' }); // a sepia map: water, roads and land cover follow

The ten colours are also the colors.* knobs:

import { getKnob, resetKnob, stylingFoundationsKnobCatalogue } from '@tomtom-org/maps-sdk/map';

getKnob(styling, stylingFoundationsKnobCatalogue, 'colors.water');   // the style's own, or derived from your land, until set
resetKnob(styling, stylingFoundationsKnobCatalogue, 'colors.roadMajor'); // one colour back to the style

The catalogue carries the summary in the table above as each knob's description, and getConfig() carries the colours with the rest of the settings.

A palette is a recolour, not an inversion. Every literal is re-derived by its offset from the style's own colour, so a palette near the loaded style's lightness lands cleanly, while one that inverts it — dark land over standardLight — pushes the derived shades to the ends of their range and washes the road hierarchy out. Pair a dark palette with standardDark and recolour from there:

await map.setStyle('standardDark');
styling.setMapColors({ land: '#161b27', water: '#2c486d', roadMajor: '#b68e54', label: '#dce0e5' });

The bar is a coherent recolour — faithful for reasonable palettes, approximate for extreme ones. The colours a mono style derives from land are the theme's exactly; the shades within each colour are re-derived from the loaded style, not pixel-matched to a compiled theme.

From a few colours, a stylesheet or an image

When the look comes as a brand's swatches, a website's CSS, a photo or a mood rather than ten named colours, the Map Theme plugin assigns the roles for you:

import {
    deriveMapColors,
    deriveMapColorsFromCss,
    deriveMapColorsFromImage,
} from '@tomtom-org/maps-sdk-plugin-map-theme';

styling.setMapColors(deriveMapColors(['#1d3f8a', '#e63312', '#f5d000', '#111111', '#f4f1ea']));
styling.setMapColors(deriveMapColorsFromCss(await cssFile.text()));
styling.setMapColors(await deriveMapColorsFromImage(fileInput.files[0]));

The accent: what a theme reaches beyond the base map

colors.accent is the colour for what is drawn on top of the map. It is a knob like the other colours — getKnob, setKnob, resetKnob and getConfig() carry it — but it paints no style layer.

It is published on the map as map.mapColors — with the ten map colours in force, and empty until a Styling Foundations module exists — and the modules that draw their own layers read it as their default, so one theme recolours the base map and the routes, areas and pins drawn on it:

import { RoutingModule, StylingFoundationsModule } from '@tomtom-org/maps-sdk/map';
import { deriveMapColors } from '@tomtom-org/maps-sdk-plugin-map-theme';

const styling = await StylingFoundationsModule.get(map);
const routes = await RoutingModule.create(map); // no colour chosen
styling.setMapColors(deriveMapColors(['#1d3f8a', '#e63312', '#f5d000', '#111111', '#f4f1ea']));
// the base map is Miró, and so is the route drawn across it
map.mapColors.accent; // the colour the route took

• A colour the caller chose always wins: routes.applyConfig({ color: '#c8102e' }) stays #c8102e through every theme change.
• The modules given none follow the accent live; without an accent, each keeps its own default.
• No knob writes a module's layers: the accent is one more input the module reads (Who owns what).
• The Map Theme plugin's deriveMapColors returns an accent, picked to read on the land.

To theme the base map alone, leave the accent out, or reset it; the modules go back to their own defaults:

import { resetKnob, stylingFoundationsKnobCatalogue } from '@tomtom-org/maps-sdk/map';
import { deriveMapColors } from '@tomtom-org/maps-sdk-plugin-map-theme';

const { accent, ...baseMapColors } = deriveMapColors(['#1d3f8a', '#e63312', '#f5d000', '#111111', '#f4f1ea']);
styling.setMapColors(baseMapColors);

// or, with an accent already set:
resetKnob(styling, stylingFoundationsKnobCatalogue, 'colors.accent');

Only those four modules read it:

• Your own colours: CustomGeoJSONModule, TrafficAreaAnalyticsModule, the flyover plugin's marker and your own MapLibre layers draw the colours you give them.
• The style's colours: TrafficIncidentDetailsModule draws the style's incident colours (Borrowed looks); base-map POI icons and the places cluster badges keep theirs (cluster.badge.color sets a badge's).

To match the theme in your own layers, read map.mapColors.accent whenever the settings change:

styling.events.on('config-change', () =>
    map.mapLibreMap.setPaintProperty('my-trail', 'line-color', map.mapColors.accent ?? '#0a3653'),
);

The demo below themes the base map, an area, pins and a route in one call:

Related guides and examples

Related guides

• Map styling — the knobs, their catalogue, presets and settings
• Borrowed looks — the module parts that follow the style's own colours instead of the accent
• Map Theme plugin — the map colours, accent included, from a few colours or an image
• TomTom Map Maker — the Foundations colours these names come from

Related examples

• Themed map — a map that opens in its own colours, themed from the first frame
• Map colours — the ten map colours, each recolouring every shade derived from it
• Map theme — the base map, an area, pins and a route themed in one call