# Brasília Bike Lanes — Interactive Map Overlay Plan Research brief for a single self-contained `index.html` map of Brasília's cycling infrastructure. No build step, CDN-only dependencies, double-click to run. Data is supplied as GeoJSON in `data/` (already being collected by parallel agents). --- ## 1. Library choice — MapLibre GL JS **Pick: MapLibre GL JS v4.x via CDN (`unpkg.com/maplibre-gl@4`).** Justification: - WebGL renders smoothly at high zoom without tile pixelation; cycle lanes need crisp lines when users zoom into the Eixo Monumental or the Plano Piloto's S1/S2 axis. - Native data-driven styling (`paint` expressions on `cycleway`/`network` properties) means we keep one GeoJSON source and color it by attribute — far cleaner than Leaflet's per-feature `style` callbacks. - Built-in `FullscreenControl`, `GeolocateControl`, `ScaleControl`, `NavigationControl` — fewer plugins. - ~290 KB gzipped vs Leaflet's ~42 KB is a non-issue for a personal desktop-first project; we trade size for fidelity, which is the stated requirement. - Free, MIT-licensed, no token required. The only Leaflet advantage (raster tile simplicity) is outweighed by vector basemap quality. Reject Leaflet: SVG/Canvas rendering becomes a bottleneck if the network grows past ~5–10k segments, and re-styling all features on filter change is sluggish. Keep Leaflet as a Plan B only if a vector basemap source disappears. --- ## 2. Basemap / tile provider ### Primary: **OpenFreeMap — `positron` style** (vector, no key) - URL: `https://tiles.openfreemap.org/styles/positron` - Free, unlimited, no signup, no API key, no usage cap. Hosted by Zsolt Ero on dedicated hardware. Funded by donations. - Three styles available out of the box: `positron` (clean light grayscale — recommended), `bright` (everyday colorful), `liberty` (rich detail). All are MapLibre-style JSON, drop-in. - Attribution: OpenStreetMap contributors + OpenFreeMap (auto-added by MapLibre when the style is loaded). - This is the right call for our use case: cycling lines need a desaturated background so the colored overlay reads. Positron is literally designed for that. ### Fallback / dark mode: **CARTO Voyager + Dark Matter** (raster) - URLs: - `https://{s}.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}{r}.png` - `https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}{r}.png` - No API key for low-traffic, non-commercial use. Personal portfolio fits inside CARTO's fair-use envelope. - Use as the dark-mode toggle and as a hard fallback if OpenFreeMap is ever down. Raster, but rendered through MapLibre's `raster` source so we don't need a second library. - Attribution: `© OpenStreetMap contributors © CARTO`. ### Rejected - **Stadia Maps / Stamen Toner**: now requires API key signup. Free for non-commercial but adds friction; key would be visible in the HTML. Skip. - **MapTiler**: 100k loads/month free but requires key and account. Skip for the same reason. - **OSM standard `tile.openstreetmap.org`**: tile usage policy forbids "heavy use" and embedding in apps. Fine for dev but not as the primary for a published file. - **Esri World Light Gray Canvas**: usable without key but Esri's current terms restrict commercial/heavy use, and the style is a little dated. Hold as third-tier fallback only. - **Mapbox**: paid + token. Off the table per constraints. --- ## 3. Cycling-specific overlay reference ### CyclOSM as toggleable basemap — **YES, include** - URL pattern (raster, three subdomains for load balancing): `https://{a,b,c}.tile-cyclosm.openstreetmap.fr/cyclosm/{z}/{x}/{y}.png` - Hosted by OpenStreetMap-France under the OSM tile usage policy (fair use, no key). Attribution: `© CyclOSM, © OpenStreetMap-France, © OpenStreetMap contributors`. - Purpose-built cycling cartography (renders cycleways, lanes, bike parking, repair stations) — gives the user a "show me the OSM reference rendering" view to sanity-check our overlay against. - Treat as a *basemap* option, not the default — its strong styling competes with our custom overlay. Toggle exposes it for verification. ### Rejected - **OpenCycleMap / Thunderforest**: requires API key, free tier capped at 150k tiles/month, key would be visible in HTML. - **Strava Heatmap**: requires authenticated session cookies. Not embeddable. Skip entirely. --- ## 4. Styling plan for cycling features Colors chosen for: (a) Okabe–Ito colorblind-safe palette adjacency, (b) high contrast against Positron's grays and Dark Matter's blacks, (c) hierarchy that reads at a glance — segregated paths jump out. | Feature | Hex | Width (light basemap) | Dash | Casing | |---|---|---|---|---| | Ciclovia (segregated cycleway) | `#0E7C3A` (deep green) | 4.5 px @ z14 → 7 px @ z17 | solid | white casing 1.5 px | | Ciclofaixa (painted lane on road) | `#1F77B4` (strong blue) | 3 px @ z14 → 5 px @ z17 | `[6, 4]` long dash | none | | Ciclorrota (signed shared route) | `#E07B00` (warm orange) | 2.5 px @ z14 → 4 px @ z17 | `[2, 4]` short dotted | none | | Bike route relation halo | `#7B2CBF` (purple) | 9 px translucent (`opacity 0.18`) | solid | renders *under* segments as a glow | Dark mode adjustments (when Dark Matter is active): | Feature | Hex | |---|---| | Ciclovia | `#3DDB7E` (brighter green) | | Ciclofaixa | `#5BA8E5` (lighter blue) | | Ciclorrota | `#FFB347` (warmer amber) | | Halo | `#C77DFF` | Notes: - Colors are distinguishable under deuteranopia and protanopia (verified against Okabe–Ito-derived greens/blues/oranges with intentional luminance separation). - The white casing on ciclovia gives a subtle "outline" effect that reads as "primary infrastructure" without screaming. - Width interpolation: use MapLibre `interpolate ['linear', zoom]` expressions so lines thicken with zoom — keeps the network visible at z11 and detailed at z18. - Hover/selected state: brighten by ~20% lightness and bump width +1.5 px; do not change hue. --- ## 5. Interactive controls Listed in priority order with the simplest implementation path. | Control | Implementation | |---|---| | Layer toggle (4 cycling layers + context layers like parks/lake) | Custom HTML checkbox panel in `