GDS — Designing a map platform in layers

Map Core provides the reusable map UX. A product team passes one or more datasets through the Map Data Contract, then composes the pieces it needs around the GDSMap component: Layer Panel, Search Dock, Context Drawer, Tool Dock, and Map Controls.

Map Kit is the batteries-included path for teams that need GDS data. It builds on Map Core with Aurora styling, MapTiler basemaps, the default map composition, GDS data orchestration, and Path of Control. Products can use GDS datasets on their own or combine them with business datasets expressed through the same contract.

The Map Data Contract gives different products and services one way to describe points, lines, polygons, layers, relationships, metadata, and search behaviour.

I designed the Map Data Contract as the canonical frontend structure between product data and the renderer. It gives Map Core one vocabulary for entities, GeoJSON geometry, layer paths, styling, relationships, search configuration, and contextual lenses.

A Map Core consumer shapes its business data into that contract. Map Kit can fetch GDS feature types and turn the response into the same structure. Because GDSMap accepts one contract or an array, the engine can render several datasets through one interaction model.

I kept the integration model explicit so teams could understand what each package supplied and where their product joined it.

The useful part of a map is not the basemap. It is the set of decisions a person can make over the data. I built a composable experience around a layer panel, search, a tool dock, map controls, and a context drawer.

The interaction model applied the same meaning to points, lines, and polygons: hover was a preview, focus meant inspection, selection was an explicit action, and related features stayed visually secondary. When states competed, selection won. That hierarchy made behaviour predictable across datasets instead of leaving each layer to invent its own cues.

The default Tool Dock includes Explore, Select, Select Area, Draw Polygon, and Route. Selection and drawing operate against the shared entity model; Route returns its start and end points to the consuming product. Map Kit adds Path of Control, which a lens can toggle to draw a dataset-coloured route over the map.

A map renderer cannot compensate for an application that sends every geometry it owns. I treated performance as a responsibility shared by services, transformations, the consumer, and Map Core.

Map Kit's data orchestrator requests visible feature types for the current bounding box. It respects minimum zoom levels, debounces viewport changes, cancels stale requests, and reuses a result when the bounding box has not changed. Map Core then renders the returned contracts and their interaction state.

Preferences followed the same philosophy. Map Core exposed a controlled model for view and layer state, while the application chose how to persist it.

A platform is not reusable if adoption begins with source-code archaeology. I made Storybook the working reference for Map Core and Map Kit, covering contracts, components, interaction states, workflows, and integration examples.

I backed that with architecture, integration, theming, accessibility, performance, deployment, and operator guides. Vitest covered package behaviour; Playwright and consumer smoke builds exercised the packages through the GDS web application and Storybook.

Both packages build to JavaScript, TypeScript declarations, and exported styles. They currently live in the GDS monorepo, with release workflows that build, test, pack, and verify them as consumable packages.