How to Build a Custom Branded Basemap

By The Kaleidr Team · Published July 25, 2026 · 16 min read

Kaleidr emblem centered over a stylized city map with analytics callouts, titled How to Build a Custom Branded Basemap for Your Website or App.

A custom branded basemap is the visual foundation beneath a product's locations, routes, boundaries, and live data. Building one requires hierarchy, readable labels, accessibility across themes, efficient rendering, and correct attribution—not merely swapping brand blue onto every road. Kaleidr Studio supports designed tiles, colors, typography, labels, icons, layers, terrain, and reusable presets, while the Kaleidr SDK can embed a designed basemap or load the published style directly in MapLibre.

The sections below walk from product task and design tokens through layer hierarchy, typography, icons, terrain, Studio workflow, two deployment paths, licensing, accessibility, and release checks. Follow the sequence in order when you need a production style; jump to Option 1 or Option 2 when the design work is already done and you only need the integration path.

A neutral vector map transformed through color, typography, labels, roads, and product overlays into a coherent branded basemap.

What Is a Custom Branded Basemap?

A basemap is the geographic canvas beneath the product-specific information in a map. The basemap normally contains reference features such as land and water, roads and paths, buildings, parks and land use, administrative boundaries, place and road labels, terrain or hillshade, and points of interest selected for context. A branded basemap applies a deliberate design system to those features so the map belongs visually to the surrounding product. The result should feel consistent with the application's colors, type, spacing, tone, and information priorities without sacrificing geographic legibility.

The MapLibre Style Specification defines a map style as a JSON document that controls which data to draw, the order in which to draw it, and how the renderer should visualize it. Sources identify the available data; layers reference those sources and define visual properties such as color, width, opacity, icons, and text. That model makes a branded basemap a reusable product asset rather than a collection of ad hoc marker colors.

How Do Basemap, Overlay, and Application Data Differ?

A reliable map separates reference geography from the information users came to see. The basemap supplies stable geographic context. Product overlays represent the application's subject. Interaction layers show temporary user or system state. Interface layers support controls and explanation. The basemap should usually be quieter than the product overlay so operational data stays dominant.

An exploded branded-map stack showing reference geography below product overlays, interaction states, and interface information.

Layer type Purpose Examples
Basemap Supplies stable geographic context Roads, water, buildings, parks, labels, boundaries
Product overlay Represents the application's subject Properties, stores, incidents, assets, service areas, routes
Interaction layer Shows temporary user or system state Selected place, hover state, AI result, search polygon, route preview
Interface layer Supports controls and explanation Legend, filters, chat panel, tooltips, attribution, status messages

A property platform may mute ordinary buildings so active listings stand out. A mobility product may emphasize road hierarchy while reducing unrelated points of interest. A tourism guide may preserve landmarks and pedestrian context while using a stronger visual treatment for curated destinations. Branding becomes useful when it improves that hierarchy; a map that merely uses more brand color can become harder to read.

What Will You Build?

This guide produces a reusable branded basemap workflow with a design brief tied to the product's actual map task, a controlled token system for color, typography, labels, lines, and surfaces, a layer hierarchy that keeps application data dominant, light, dark, and high-contrast testing, OpenStreetMap attribution and tile-delivery checks, a Kaleidr-hosted embed option, a direct MapLibre style option, and a release and regression-testing process.

Kaleidr currently documents five built-in style identifiers for its designed basemap product: kaleidr-morning, kaleidr-afternoon, kaleidr-night, kaleidr-editorial, and kaleidr-plain. Kaleidr Studio separately describes custom colors, typography, labels, icons, datasets, overlays, reusable presets, terrain, 3D buildings, and hillshade. The public developer documentation demonstrates how to serve a designed style, but it does not document every Studio publishing step for organization-specific custom style IDs. Confirm the final publish workflow and identifier inside the current Studio interface before production deployment.

How Should You Start With the Product Task?

A strong basemap begins with a product decision, not a color picker. Ask what the primary user task is, which geographic features help complete that task, which features distract from it, what information must remain legible at every zoom, which product overlays need the strongest contrast, whether the map appears beside dense interface chrome or as a full-screen experience, whether the same style must serve desktop, mobile, screenshots, and embedded views, and whether the product needs day, night, or accessibility variants. A store locator and a logistics dashboard should not share the same geographic emphasis simply because they share a logo.

For a store locator, prioritize major and local roads, neighborhood and city labels, recognizable landmarks, clear store markers, and route context, while reducing minor land-use categories, unrelated business labels, decorative terrain, and detailed building emphasis at small scales. For real-estate discovery, prioritize neighborhood names, transit, parks and water, street hierarchy, building footprints at close zoom, and property or search-area overlays. For an operations dashboard, prioritize roads, service areas, administrative boundaries, and asset context, with dark or low-chroma surfaces that support alert colors, clear selected and unselected states, and stable labels that do not obscure incident markers.

How Do You Define a Map Design Token System?

Create map tokens before editing individual layers. Tokens keep the style coherent and make future variants easier to maintain. A practical token set includes surfaces, networks, labels, and operational accents:

map.background
map.land
map.water
map.park
map.building
map.boundary
map.road.motorway
map.road.primary
map.road.secondary
map.road.local
map.road.casing
map.label.country
map.label.city
map.label.neighborhood
map.label.road
map.label.poi
map.label.halo
map.overlay.primary
map.overlay.secondary
map.selection
map.warning
map.route

Do not map every token directly to a corporate marketing color. Product brand systems often include colors designed for buttons or illustrations that fail on a dense geographic canvas. Use brand colors selectively for active product overlays, selected features, routes, search areas, primary calls to action, and a small number of meaningful reference features. Use restrained neutral colors for most reference geography.

How Do You Build the Visual Hierarchy?

The MapLibre Style Specification lists the layers in drawing order. Later layers generally draw above earlier layers, so layer order is part of the information architecture. A common basemap stack places background, land cover and terrain, water, parks and land use, buildings, roads and road casings, boundaries, place labels, road labels, and contextual points of interest below product overlays and interaction states. The exact order depends on the renderer and style, but the principle remains stable: large geographic surfaces sit below networks, labels, and product-specific information.

Every layer does not need equal saturation, opacity, or detail. Useful controls include lowering the opacity of low-priority polygons, reducing minor-road contrast at small zooms, hiding low-value points of interest, showing building footprints only after a useful zoom threshold, limiting administrative boundaries to the scales where they aid orientation, and delaying local street labels until the user is close enough to need them. A quiet basemap increases the perceived clarity of application data without making the map empty.

Road styling usually requires both hierarchy and casing. Consider motorway through service classes, width by zoom, line casing beneath the road fill, tunnels and bridges, ramps and divided roads, pedestrian paths and cycleways, and label density. A brand color applied to every road creates a flat network in which nothing appears more important than anything else. Use width, brightness, casing, and controlled hue shifts to establish hierarchy, and reveal local roads only at closer scales.

How Should You Design Labels, Icons, and Contrast?

Typography is one of the strongest brand signals in a map, but label rendering has technical constraints. A style document may reference glyph resources through a URL template. The MapLibre Style Specification requires glyph URLs to include {fontstack} and {range} placeholders, while sprite resources supply icons and patterns referenced by symbol layers. A font named in a design system is not automatically available to the map renderer; the glyph set must be served in the format and coverage expected by the style.

A branded map label and icon system showing typography hierarchy, halos, glyphs, sprites, interaction states, and contrast testing.

Define label roles rather than applying one font size everywhere: country, region or state, city, neighborhood, road, transit, point of interest, water body, and product annotation. Use size and weight for hierarchy, restrained letter spacing, halos for contrast over changing geography, different colors for water, administrative, and road labels where useful, zoom thresholds that prevent crowding, and language and script coverage appropriate to the audience. Test labels over both the lightest and darkest regions of the map, because a label that looks correct over land may disappear over water, terrain, or a satellite layer.

Map icons should operate as a compact symbol system. The MapLibre sprite specification uses sprite image and metadata resources to make icons and patterns available to symbol and fill layers. Before adding branded icons, define a consistent stroke and fill style, minimum rendered size, light and dark variants, selected and unselected states, semantic meaning, collision and overlap rules, and accessible text equivalents outside the canvas. Do not force the corporate logo into every point-of-interest marker. Repetition reduces map clarity and can make the interface feel promotional rather than functional.

When Should You Add Terrain and 3D?

Kaleidr Studio describes support for elevation, terrain, hillshade, and extruded buildings. MapLibre also documents terrain and fill-extrusion layers for 3D buildings. Use those capabilities when they improve the user's spatial understanding: terrain for outdoor, mobility, infrastructure, and risk workflows; hillshade for landform context; 3D buildings for close-scale urban orientation; and extrusions for height or volume that matters to the task. Avoid 3D when it obscures markers, increases visual noise, creates unnecessary GPU load, makes labels harder to read, or implies precision the source data does not support. A branded map is not stronger merely because it is more dimensional.

The basemap and the application's data should remain separate whenever possible. MapLibre sources state which data the map should display, while layers define how to render that data. The same source can support multiple visual layers, such as a polygon fill, outline, selected state, and label. For product overlays, define source ownership, stable identifiers, geometry type, update frequency, zoom range, filtering rules, selected and hover states, error and empty states, and privacy constraints. Keep operational colors distinct from basemap colors so a red alert does not compete with red roads and a blue selected region does not disappear into blue water.

How Do You Build in Kaleidr Studio?

Kaleidr Studio uses a Prompt → Process → Refine → Deploy workflow and describes custom design, content, style, and interaction controls. For a branded basemap, define the map purpose, choose a visual direction, set colors and hierarchy, configure typography and labels, add or reuse layers, evaluate terrain and 3D only when they improve comprehension, test representative locations and zooms, publish the designed basemap, and embed or load the style. Kaleidr's public Studio page confirms the available design areas, but the exact organization-specific publishing controls may evolve. Record screenshots and the final style identifier as part of the release process.

Which Deployment Path Should You Choose?

Kaleidr documents two implementation models for a designed basemap. The tile embed owns its own map surface and receives camera updates through the SDK's embed interface. Direct MapLibre loading points a host-owned map at the published style JSON so the application can add its own sources, layers, and interactions. Choose the embed when implementation speed matters and the basemap can own its surface. Choose MapLibre when the host needs full renderer control.

Two basemap deployment paths: a Kaleidr tile embed and a host-controlled MapLibre map using a published Kaleidr style JSON.

Option 1: Embed the Kaleidr basemap

The following example is adapted from the current official documentation. Use a publishable key restricted to allowed origins; the SDK exchanges the key for a short-lived, origin-bound session. The key needs the maps capability scope for tiles. API keys are currently included with Pro and Enterprise plans. See Get an API key and Tiles — embed a designed basemap.

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

<kaleidr-map
  product="tile"
  publishable-key="YOUR_PUBLISHABLE_KEY"
  style-id="kaleidr-morning"
  center="-0.12,51.5"
  zoom="11"
  style="height: 480px">
</kaleidr-map>

The current built-in style IDs are kaleidr-morning, kaleidr-afternoon, kaleidr-night, kaleidr-editorial, and kaleidr-plain. Use the embed option when the basemap can own its own map surface, implementation speed matters, the application can communicate through the documented embed interface, and the team does not need direct control over every renderer method.

Option 2: Load the style directly in MapLibre

Kaleidr also documents using the same basemap directly in a host-owned MapLibre map through its published style JSON. The style URL and built-in identifier below come from Kaleidr's current Use a designed basemap guide. For an organization-specific custom style, substitute the published style URL documented by the current Studio workflow.

<link
  href="https://unpkg.com/maplibre-gl@6.0.0/dist/maplibre-gl.css"
  rel="stylesheet"
/>

<div id="map" aria-label="Branded interactive map"></div>

<script type="module">
  import * as maplibregl
    from "https://unpkg.com/maplibre-gl@6.0.0/dist/maplibre-gl.mjs";

  const map = new maplibregl.Map({
    container: "map",
    style: "https://cdn.kaleidr.com/styles/kaleidr-morning.json",
    center: [-0.12, 51.5],
    zoom: 11
  });

  map.addControl(new maplibregl.NavigationControl());

  map.on("error", (event) => {
    console.error("Basemap or renderer error:", event.error ?? event);
  });
</script>

Use the direct MapLibre option when the host application needs direct access to the map instance, product overlays must be added as sources and layers, the team needs precise control over events, camera, controls, and runtime styling, or the basemap is one part of a larger interactive application.

How Should You Version and Cache the Integration?

Kaleidr serves the loader and product bundles through version-pinned paths such as https://cdn.kaleidr.com/embed/v1/kaleidr.js and https://cdn.kaleidr.com/embed/v1/tile.js. Backward-compatible updates ship under the same major path. A breaking embed or postMessage change would use a new major path such as /embed/v2/. Kaleidr advises against fingerprinting or self-hosting the SDK bundles unless the team intends to pin a specific build independently. See CDN versioning.

Style assets and tiles should also use an explicit cache and release strategy: version significant style changes, avoid replacing a production style without regression testing, record the published style ID and date, test sprite and glyph cache invalidation, preserve a rollback target, and monitor failed style, tile, sprite, and glyph requests.

What Attribution and Tile Rules Apply?

OpenStreetMap data is open data, but attribution remains required. OpenStreetMap states that users may use the data for any purpose as long as they credit OpenStreetMap and its contributors. Kaleidr's pricing page states that its open basemap data derives from OpenStreetMap and Overture Maps and requires attribution to OpenStreetMap contributors wherever the tiles appear. See the OpenStreetMap copyright page; the OpenStreetMap Foundation also publishes attribution guidelines for interactive maps and other produced works.

Do not confuse open data with unlimited use of the OpenStreetMap Foundation's public tile servers. The OSMF tile usage policy explains that the public raster tile service has limited donated capacity and imposes usage requirements. A production product should use a provider, a compliant hosted tile service, or self-hosted infrastructure rather than treat tile.openstreetmap.org as a free commercial CDN.

For every release, verify that attribution remains visible and readable, the attribution link points to the required license or copyright page, any additional dataset or imagery credits are present, satellite and hybrid imagery follow their separate commercial licenses, and the provider's storage, caching, and redistribution terms are respected. Kaleidr currently states that its open OpenStreetMap-based basemap tiles may be used commercially within the plan's monthly map-load allowance. Satellite and hybrid imagery are separate licensed layers and are not included in the open tile offering.

How Do You Test Accessibility and Performance?

A map canvas should not be the only place where essential information appears. Test label contrast over land, water, roads, buildings, and terrain; overlay contrast against every basemap variant; selected and unselected states without relying on color alone; route and boundary visibility for common color-vision deficiencies; keyboard access to controls and result lists; screen-reader equivalents for markers and selected features; readable attribution and control labels; and reduced-motion behavior for camera transitions where appropriate. Use real screenshots at representative zooms, because generic interface contrast checks do not capture every background a label or marker may cross.

A custom style can affect startup and interaction performance through style JSON size, number of sources, number and complexity of layers, glyph and sprite requests, tile size and cache behavior, terrain and 3D rendering, label collision work, live or frequently updated overlays, and device GPU limitations. Measure time until the first useful map appears, style-load time, failed tile, glyph, and sprite requests, frame rate during pan, zoom, pitch, and rotation, memory use on representative mobile devices, impact of live overlays, and map-load and tile usage by session. Remove hidden or redundant layers rather than assuming the renderer makes them free.

What Quality Checks Belong in Release?

Test the basemap across geography, scale, theme, and product state before approving a release. A style should not be approved based on one attractive city screenshot.

Test dimension Required cases
Geography Dense urban, suburban, rural, coastal, mountainous, international
Zoom Regional, city, neighborhood, street, building
Theme Light, dark, high contrast, brand campaign variant
Data state No overlays, normal results, dense results, selected result, route, alert
Device Desktop, tablet, low-end mobile, high-density display
Network Fast, slow, intermittent, cached, cold start
Language Long place names, multiple scripts, right-to-left where supported
Accessibility Keyboard, screen reader, color-vision simulation, zoomed text

The following event names are editorial recommendations rather than claims about automatically emitted Kaleidr Analytics events:

basemap_loaded
basemap_load_failed
basemap_style_selected
basemap_style_changed
basemap_theme_changed
basemap_tile_error
basemap_attribution_opened
map_overlay_added
map_overlay_toggled
map_3d_enabled
map_session_completed

Useful metrics include first useful map time, successful style-load rate, tile error rate, map-load usage, renderer frame rate, session duration, overlay interaction rate, selected-result rate, route or workflow completion, theme-switch frequency, conversion by basemap variant, and support incidents related to map legibility. Do not declare a basemap successful because it looks distinctive. Measure whether users find, interpret, and act on the product's geographic information more effectively.

What Mistakes Should Teams Avoid?

Mistake What happens Recommended correction
Applying brand color everywhere Geographic hierarchy collapses Reserve strong brand color for selected features and product overlays
Styling the basemap before defining the task The map looks polished but does not support the workflow Start with user decisions and required geographic context
Keeping every point-of-interest label Important product data competes with unrelated labels Remove or delay low-value labels by zoom and category
Using a corporate font without glyph support Labels fail or fall back inconsistently Confirm glyph hosting, character coverage, and renderer compatibility
Treating icons as decoration Symbols become inconsistent and ambiguous Create a semantic sprite system with states and text equivalents
Adding 3D by default Performance and readability decline Use terrain and extrusions only where they explain relevant structure
Mixing overlay and basemap colors Selected or alert states disappear Maintain separate reference and operational color tokens
Removing attribution The map violates source requirements Keep readable attribution linked to the required source and license
Using public OSM tile servers as a production CDN Usage may violate policy or be blocked Use a compliant provider, Kaleidr-hosted tiles, or self-hosted infrastructure
Replacing a production style without versioning Visual regressions reach users without rollback Version releases and preserve a tested previous style

Final Implementation Checklist

  • Product map task documented
  • Basemap, overlay, interaction, and interface layers separated
  • Geographic hierarchy defined
  • Map design tokens approved
  • Road classes tested by zoom
  • Label hierarchy and halos tested
  • Glyph coverage confirmed
  • Sprite and icon system documented
  • Product overlay colors kept distinct
  • Terrain and 3D justified by the use case
  • Representative global locations reviewed
  • Light, dark, and accessibility variants tested
  • OpenStreetMap and other attribution visible
  • Tile-provider terms confirmed
  • Publishable key origin restrictions configured
  • maps capability scope confirmed
  • Embed or direct MapLibre path selected
  • Style ID and release version recorded
  • Error and loading states implemented
  • Performance tested on mobile hardware
  • Map-load and tile usage monitored
  • Rollback style preserved

Final Verdict

A custom branded basemap should make a map feel native to the product while improving the hierarchy of the information users need. Color, typography, labels, icons, terrain, and 3D are implementation tools—not the objective. The strongest workflow begins with the product task, separates reference geography from operational overlays, defines reusable design tokens, tests multiple locations and zooms, preserves source attribution, and deploys through a versioned style and tile-delivery path.

Kaleidr supports two documented implementation models: embed a designed basemap with product="tile", or load the published Kaleidr style JSON directly into a MapLibre map. Use the embed when the basemap can own its surface and integration speed matters. Use the direct MapLibre path when the host application needs full map control and must add its own sources, layers, and interactions.

Design a Basemap in Kaleidr Studio

Create map styles, labels, layers, terrain, 3D buildings, and reusable presets for a branded spatial experience. Start from the product task, apply tokens selectively, and publish a style you can embed or load in MapLibre.

Open Kaleidr Studio

Add the Designed Basemap to Your Product

Review the tile embed, MapLibre style URL, browser key, origin restriction, usage, and CDN-versioning documentation before selecting the integration path.

Read the Kaleidr Tile Documentation

FAQs

What is a custom branded basemap?

A custom branded basemap is a reusable geographic reference style whose colors, typography, labels, icons, roads, surfaces, and contextual layers are designed to fit a product's visual system and user task. The basemap provides context; product overlays carry the application's subject matter.

Is a basemap the same as my application data?

No. The basemap provides geographic context such as roads, water, buildings, and labels. Application data represents the product's properties, stores, assets, incidents, routes, or other subject matter and should normally appear above the basemap.

Can I use my brand font on a vector map?

Only when the renderer can load compatible glyph resources for the font and required character ranges. Confirm licensing, glyph generation, hosting, language coverage, and fallback behavior before choosing the typeface.

Can Kaleidr basemaps be used in MapLibre?

Yes. Kaleidr documents loading a published Kaleidr style JSON directly as the style value when creating a MapLibre map. The host application then adds its own overlays and interactions on top of that style.

Can I embed a Kaleidr basemap without managing MapLibre directly?

Yes. The Kaleidr SDK documents a product="tile" custom element and imperative mount option that embeds a designed basemap by style ID. The embed owns its own map surface and communicates through the documented interface.

Which Kaleidr basemap styles are currently documented?

The current developer documentation lists kaleidr-morning, kaleidr-afternoon, kaleidr-night, kaleidr-editorial, and kaleidr-plain. Organization-specific Studio styles may publish under additional identifiers.

Do Kaleidr tiles require an API key?

Browser tile embeds use a publishable Kaleidr key with the appropriate maps capability and allowed-origin restrictions. API keys are currently included with Pro and Enterprise plans.

Can I use Kaleidr's open basemap tiles commercially?

Kaleidr's current pricing page says commercial use is allowed within the monthly map-load allowance. Higher-volume production use is included with Pro, and Enterprise supports custom volume through an independent CDN. Satellite and hybrid imagery remain separately licensed.

Do I need to attribute OpenStreetMap?

Yes. OpenStreetMap requires attribution to OpenStreetMap and its contributors. Kaleidr also states that attribution is required wherever its open OpenStreetMap-based tiles appear. Keep the credit visible and linked to the copyright or license information.

Can I use OpenStreetMap's public tile servers for a commercial product?

OpenStreetMap data is open, but the OpenStreetMap Foundation's public tile servers have a separate usage policy and limited donated capacity. A production application should use a compliant tile provider or self-hosted infrastructure rather than assume unrestricted CDN use.

Should every branded map use terrain and 3D buildings?

No. Terrain and 3D should be used when they improve spatial understanding. They can reduce readability and performance when they do not support the user task.

How should I measure whether the basemap is effective?

Measure style-load reliability, first useful map time, tile errors, overlay interaction, result selection, workflow completion, accessibility issues, support incidents, and conversion. Visual distinctiveness alone is not a sufficient success measure.

References

@misc{kaleidr_tiles,
  title  = {Tiles --- embed a designed basemap},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 25 July 2026},
  url    = {https://docs.kaleidr.com/sdk/tiles}
}

@misc{kaleidr_use_tiles,
  title  = {Use a designed basemap},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 25 July 2026},
  url    = {https://docs.kaleidr.com/guides/use-tiles}
}

@misc{kaleidr_studio,
  title  = {Create Custom Maps with AI Map Maker},
  author = {{Kaleidr}},
  note   = {Accessed 25 July 2026},
  url    = {https://kaleidr.com/studio}
}

@misc{maplibre_style_spec,
  title  = {MapLibre Style Specification},
  author = {{MapLibre}},
  note   = {Accessed 25 July 2026},
  url    = {https://maplibre.org/maplibre-style-spec/}
}

@misc{osm_copyright,
  title  = {Copyright and License},
  author = {{OpenStreetMap}},
  note   = {Accessed 25 July 2026},
  url    = {https://www.openstreetmap.org/copyright}
}

@misc{osm_tile_policy,
  title  = {Tile Usage Policy},
  author = {{OpenStreetMap Foundation}},
  note   = {Accessed 25 July 2026},
  url    = {https://operations.osmfoundation.org/policies/tiles/}
}