Map Builder Controls Spec
Generic chart styling breaks down on maps. This spec defines layer-aware controls for projections, choropleths, point symbols, flows, labels, legends, interactions, and geometry joins.
1. Design Rules
Layer-specific panels
Only show controls that apply to the active layer type. Region borders are not point marker outlines, and flow width is not polygon stroke.
Map-native semantics
Use projection, join key, graticule, bundling, and clustering instead of generic controls like border radius that have no geographic meaning.
Conditional visibility
A builder should expose different controls for polygons, points, flows, labels, legends, and data joins.
No fake controls
Do not render unsupported controls. For example, border radius should stay hidden unless a layer uses rectangular symbols.
2. Layer Visibility
Base Map
1 section visible
Region Layer
1 section visible
Point Layer
1 section visible
Flow Layer
1 section visible
Labels
1 section visible
Legend
1 section visible
Interaction
1 section visible
Data Binding
1 section visible
3. Control Inventory
Base Map
Projection, frame, and geographic reference settings.
Choose how lat/lon coordinates are projected onto the canvas.
Move the map viewport vertically.
Move the map viewport horizontally.
Scale the projected map without changing the container size.
Rotate the map to emphasize a geography or flow direction.
Auto-frame the geometry bounds around visible data.
Display latitude and longitude reference lines.
Draw coastline outlines for geographic context.
Show country boundaries on top of the base layer.
Region Layer
Polygon fill, borders, and choropleth behavior.
Base fill for regions when no quantitative color encoding is used.
Choose the region color encoding mode.
Lower bound for region value encoding.
Upper bound for region value encoding.
Fallback fill for unmatched or null regions.
Outline color for region boundaries.
Outline thickness for polygons.
Transparency of region outlines.
Interaction state used while hovering a region.
Point Layer
Markers, clustering, and point collision behavior.
Choose the point mark geometry.
Base symbol size for point layers.
Smallest symbol size when a field drives marker size.
Largest symbol size when a field drives marker size.
Fill color for markers.
Outline color for markers.
Outline thickness for markers.
Group dense point layers into aggregate markers.
Resolve overlapping points and labels.
Flow Layer
Directional lines, routes, and movement encoding.
Base color for route or flow lines.
Base thickness for line layers.
Transparency of flow lines.
Amount of curvature applied to routes.
Stroke pattern for emphasizing state or uncertainty.
Show directionality at the end of each flow.
Bundle similar routes to reduce clutter.
Labels
Text source, placement, and readability.
Display labels for map features.
Data field used for label content.
Label text size.
Label fill color.
Outline behind text for contrast.
Thickness of the label halo.
Rule used when not all labels fit.
Shorten long names to fit dense layouts.
Legend
Legend visibility, format, and placement.
Display a map legend.
Choose the legend visual treatment.
Visible title for the legend.
Anchor the legend within the map frame.
Format used for legend values.
Interaction
Selection, tooltips, and viewport behavior.
Show tooltip content on hover.
Fields included in the tooltip payload.
Enable selection on click.
Allow multiple selected map entities.
Allow users to navigate the viewport directly.
Configure what happens when a feature is selected.
Data Binding
Geometry sources and data join rules.
GeoJSON or TopoJSON source identifier.
Field used to match tabular data to map features.
Field used for encoding or aggregation.
Fallback behavior when a region does not join.
Method used when multiple records map to one feature.