Map colours and the accent

The most common styling ask — "our map in our brand colours" — is one call to the Styling 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:

const styling = await StylingModule.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. What each reaches:

One name fans out to every layer and shade the style built from it. roadMajor recolours the motorway line, the trunk line one shade lighter, their outlines darker, 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 result is a coherent recolour with the shade relationships preserved rather than a flat fill. The style is its own manifest: the offsets are measured off the loaded style, not shipped as a table, so the mechanism follows the style to its next version.

Land-use and building tints in a hue of their own — a hospital's pink, a campus's cream, a shopping area's yellow — are not shades of any of the ten. They keep their hue and follow artificial's lightness, and their saturation scales with its luminance the way the style's theme derives them, so a dark built-up colour darkens and mutes them too — whatever its own hue or saturation, a grey included.

The mono styles set only land and derive the other nine from it, the way their theme compiles them. On those, land alone recolours the whole map with the theme's own formulas, 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 knobs (colors.water, …), so get('colors.water') reads the style's own base colour — or the one derived from your land — until one is set, the catalogue carries the summary above as each description, reset('colors.roadMajor') restores one, and getConfig() carries the colours along with the rest of the settings.

A palette is a recolour, not an inversion. Because every literal is re-derived by its offset from the style's own colour, a palette that stays 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, whose shades already run dark, and recolour from there:

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

Fidelity bar: a coherent recolour with preserved shade relationships — visually faithful for reasonable palettes, approximate for extreme ones. The ten colours a style derives from land are the theme's exactly; the shades within each are re-derived from the loaded style, so pixel parity with a compiled theme is not the goal.

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:

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 — get, set, reset and getConfig() carry it — but it paints no style layer.

It is published on the map as map.mapColors, 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, StylingModule } from '@tomtom-org/maps-sdk/map';
import { deriveMapColors } from '@tomtom-org/maps-sdk-plugin-map-theme';

const styling = await StylingModule.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, and without an accent each keeps its own default.

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

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

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

Only those four modules read it. CustomGeoJSONModule, TrafficAreaAnalyticsModule, the flyover plugin's marker and your own MapLibre layers draw the colours you give them, TrafficIncidentDetailsModule draws the style's incident colours (Borrowed looks), and base-map POI icons and the places cluster badges keep theirs (cluster.badge.color sets a badge's). To match the theme, 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 Map Theme plugin's deriveMapColors returns the accent, picked to read on the land. No knob writes a module's layers: the accent is one more input the module reads (Who owns what). 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