Map view

Problem Context

• Locations, assets, incidents, events, service areas, deliveries, rooms, or routes are meaningful because of where they are.
• Users may need to pan, zoom, search within bounds, inspect clusters, choose a nearby item, compare distance, or understand coverage.
• Maps often combine basemap tiles, vector layers, markers, routes, polygons, popups, clustering, filters, and browser geolocation.
• Location permission, stale tiles, dense markers, hidden layers, offscreen popups, and unsynchronized fallback lists can make a map misleading.
• Map view must remain usable for keyboard users, low-vision users, users who deny location, and users who need a structured list instead of visual geography.

Selection Rules

• Choose Map view when spatial relationship, proximity, coverage, route, region, or real-world placement changes the user's decision.
• Use list view when the main task is scanning object summaries and location can be represented as text or a distance sort.
• Use table when users need aligned field comparison, bulk review, or export of records.
• Use calendar view when time placement, duration, availability, or recurrence matters more than geography.
• Use data visualization when the task is aggregate trend, distribution, or metric analysis rather than choosing place-level objects.
• Use search results when ranked matching is primary and map position is secondary.
• Cluster dense markers and disclose cluster counts when markers overlap or density makes individual selection unreliable.
• Show the current area, active layers, filters, location source, selected marker, and result count so the map's scope is not ambiguous.
• Provide a fallback list, table, or accessible result summary that stays synchronized with the map bounds and filters.
• Avoid Map view when coordinates are decorative, approximate without disclosure, or unrelated to the user's decision.
• Avoid Map view as the only control when geolocation permission or map tile loading can fail.

Required States

• Default map state with visible viewport, zoom level or distance context, markers, layer state, result count, and synchronized fallback list.
• Marker selected, marker focused, popup open, popup dismissed, side detail open, and selected item in fallback list.
• Clustered markers, expanded cluster, dense overlap, empty region, filtered region, hidden layer, and hidden-result count states.
• Panning, zooming, search-this-area, fit-to-results, route preview, radius selection, and layer toggle states.
• Geolocation requested, allowed, denied, unavailable, manual-location fallback, and approximate-location disclosure states.
• Loading tiles, failed tiles, stale map data, slow network, offline fallback, and attribution visible states.
• Keyboard marker navigation, list fallback navigation, popup focus return, and non-pointer route or selection states.
• Responsive state where map controls, selected detail, bounds count, and fallback list remain reachable on mobile.

Interaction Contract

• Markers, shapes, routes, clusters, and overlays represent explicit coordinates, features, or geographic areas, not decorative positions.
• Panning, zooming, filtering, layer toggling, and search-this-area update visible markers, counts, selected detail, and fallback list from the same result set.
• Selecting a marker opens a popup or detail that names the place, explains relevant distance or status, and provides a keyboard path back to the marker and fallback list.
• Clusters expose count and category composition when useful, and users can expand, zoom, or inspect contained items without losing map context.
• Geolocation is optional unless the task truly requires it; denied or unavailable location provides manual search, saved location, current map area, or list fallback.
• Legends and text labels explain marker color, shape, heat, route, polygon, radius, and layer meaning.
• Distances, routes, travel times, and service areas state origin, unit, mode, approximation, and stale-data status when those affect the decision.
• Keyboard and assistive-technology users can reach layer controls, search, result list, selected place details, and map movement alternatives without pointer-only gestures.

Implementation Checklist

• Define feature schema: id, name, coordinate, geometry type, category, status, distance, availability, popup fields, route metadata, layer, timestamp, and permissions.
• Define viewport model: center, zoom, bounds, selected feature, active filters, active layers, result count, cluster state, and fallback-list ordering.
• Implement marker selection, popup or side detail, fit-to-results, search-this-area, cluster expansion, layer toggles, radius or route preview, and manual location fallback.
• Keep map markers, cluster counts, fallback list, search results, and selected detail synchronized after pan, zoom, filter, layer, and geolocation changes.
• Model empty region, dense cluster, denied location, unavailable geolocation, stale data, failed tiles, hidden layer, offscreen popup, and mobile stacked layouts.
• Show attribution, legends, scale or distance context, location source, and result scope near the map.
• Test keyboard access, popup focus return, marker labels, high marker density, long place names, small screens, slow tiles, and denied browser permissions.
• Use a proven map SDK or service for projection, panning, tile loading, clustering, geolocation, and geometry math in production rather than inventing spatial math.

Common Generated-UI Mistakes

• Using a map as decoration when the positions do not affect the task.
• Showing markers without labels, selected state, popup detail, count, or fallback list.
• Letting dense markers overlap without clustering or zoom guidance.
• Treating geolocation denial as a dead end.
• Changing map filters without updating list results and result counts.
• Showing route, distance, radius, or service area without units, origin, mode, or approximation.
• Hiding layer meaning behind color-only markers with no legend.
• Making panning, zooming, popup opening, or marker selection pointer-only.

Critique Questions

• What spatial decision does the map make easier than a list, table, calendar, or chart?
• Can users tell the current area, zoom, layer state, result count, and selected marker?
• Do markers, clusters, popups, fallback list, filters, and bounds update from the same data?
• What happens when markers overlap, map tiles fail, location permission is denied, or the selected marker moves offscreen?
• Can keyboard and assistive-technology users inspect places and complete the task without dragging or hovering on the map?
• Would a list view, table, calendar view, data visualization, or search result list better fit the task?