The map is the starting point. Search, discovery, transport and saved places are deliberate tasks; regional data coverage does not define the user's destination or interests.
- Start with an unselected map, a search field, a location control and access to transport, saved places and settings. Show result pins, category choices and result sheets after the corresponding action.
- Until a usable location is available, reopen the last map view stored on the device (rounded to about 100 m, removable in Privacy e fonti), else a Turin overview labelled Panoramica di Torino. A fallback center is a viewport, never an inferred user position, favourite place or route origin labelled as the user's position.
- Locate centres the camera on the first fix it produces, including a fix that arrives after Android's permission dialog suspended the request. Panning, opening a place or stop, or searching withdraws that intent.
- When location is already authorized, acquire a fresh foreground fix. Keep manual map browsing available during acquisition and after failure. Preserve an intentional map movement while a request is pending.
- Distinguish permission denied, device location disabled, acquisition in progress, unavailable fix and stale or inaccurate navigation fixes. An absent coordinate alone does not establish that GPS is disabled. Pair failures with a relevant retry or settings action.
- Request additional precision only for a task that needs it. Navigation requires its own fresh precise fix; a browsing coordinate or map center cannot satisfy that requirement.
- An empty search has no selected category or automatic discovery results. Put category shortcuts inside the search interaction. Category selection, typed search, transport and saved places reveal their own results and pins.
- Clearing or closing a search returns to the unselected map. Map movement alone does not begin discovery; searching a changed area is explicit.
- Submitting a search or choosing a category frames its leading nearby results once, above the sheet. Panning before they arrive keeps the user's view; typing alone never moves the map.
- Typed search matches every word somewhere in a place: its name (exact and prefix names rank first, one typo at most), its address including house numbers (exact), an Italian category word (
farmacia,bar) or a neighbourhood from the bundled OpenStreetMap gazetteer (Eataly Lingotto,bar San Salvario). Linking words (in,a,di) are optional. A neighbourhood alone returns the neighbourhood, not every business inside it; its reading area is an approximate radius around the OSM node, never a boundary. Results say what they are: venue, address (Indirizzo), street (Via), area (Quartiere), GTT stop or line. A typed stop code (472,fermata 472) leads the list, a line name (15,M1,linea 4) offers its three stops nearest the searched area, and stops found by name follow the places unless the query starts withfermata. Stops and lines come from the bundled GTT catalog and appear in either search policy. - Route planning starts from a fresh position or a deliberately chosen origin. Cancelling origin selection returns to the destination; a fallback viewport never silently becomes the departure point.
- The planner shows Da and A as two editable fields with a swap button. Each opens a search inside the planner (the same local, stop and, when allowed, Photon search, plus saved places); the origin editor also offers La tua posizione (a fresh fix) and Scegli sulla mappa. Back closes the editor before the planner. Swapping needs a settled origin; a device origin swapped into the destination is that fixed position, not a live one. Changing either endpoint keeps the planning session and frames the new route once.
- Transit time is one chip (Partenza adesso, Partenza 17:45 · domani, Arrivo entro 09:00 · gio 15 ott). It opens Partenza/Arrivo, Adesso and Android's own date and time dialogs, all in Europe/Rome whatever the device zone; each choice plans again. Nonexistent and ambiguous minutes at daylight-saving changes are refused with a message.
- Apri in un’altra app on a place and on the planner destination sends
geo:lat,lon?q=lat,lon(Nome)to Android, which lets the user pick Organic Maps or another map app. The app itself sends nothing anywhere for this; the chosen map app receives the place and handles it under its own privacy terms. Organic Maps' geo URL parser reads the coordinates and the percent-encoded label fromq(itsgeo_url_tests.cpp,GeoURL_GeoLabel, checked on 2026-11-02 at upstream commit fb0ea2c); parentheses in a name are replaced because they would end the label. - Place details keep Indicazioni and Salva as the primary pair, then website (shown without scheme), phone and the hand-off. Fonti e dettagli lists every contributing source record with the field it supplied, its licence and its own date, Overture's existence estimate (never "open now"), and states that no used source supplies opening hours.
- Give one task the sheet at a time: results, place, stop, route planning or settings. Keep the map usable alongside it and provide a clear return to the map. Sheet titles and actions take precedence over explanatory text. Keep transport and saved shortcuts on the neutral map; task cards replace that chrome. Empty search uses a horizontal shortcut row.
- List distances are measured from the device when its fix is under five minutes old; otherwise they are measured from the centre the map currently shows and say dal centro mappa. A selected stop or place shows a distance only from the device. Show OpenStreetMap and Overture categories with Italian labels and a generic fallback, never a raw tag.
- Show coverage boundaries, result limits and data warnings with the results they explain. Keep mandatory map attribution accessible. Preserve place provenance, source timestamps, and live, scheduled, stale and unavailable distinctions in their relevant detail views.
- Keep Italian action names stable and direct. Use compact system typography and restrained surfaces; the geographic content supplies the visual detail. Maintain accessible text contrast and touch targets when reducing chrome.
Appearance offers Sistema, Chiaro and Scuro; Sistema is the default and follows Android's dark theme. The choice is stored on the device. An unreadable saved choice falls back to Sistema without overwriting it until the user chooses again. src/theme resolves the choice once. On Android, the colours come from the :root and prefers-color-scheme: dark variables in global.css. NativeWind binds them to the scheme set through Appearance, so a live switch repaints views styled with these classes (pressables excepted; see Live switches below). Web sets the same variables inline. Components use semantic NativeWind colours (bg-surface, bg-surface-raised, text-primary, text-secondary, bg-action/text-on-action, text-caution, text-danger, text-success, and transit text-live, text-scheduled, text-stale, text-cancelled), never literal hex classes or dark: variants; dividers use useHairlines(). Native props, icons and map layers read the same values from useTheme(). Tests hold every text role to WCAG AA (4.5:1) on every surface in both palettes. Live, scheduled, stale and cancelled states keep their text labels; colour supports them but never carries them alone.
The basemap follows the resolved appearance: avoid-light or avoid-dark, both generated from the bundled OpenFreeMap Liberty document (notice). The basemap is nearly greyscale: hierarchy comes from lightness and width, with a faint green hint on parks. POIs are small grey dots with text, transit stops are rings and stations bold rings. Colour on the map belongs to app overlays: the route (white in dark, black in light, with a contrasting casing), selection rings in the same ink, the position dot and live states in green, and caution in amber. Key amenities name their category in words, never by colour. Status bar icons, navigation bar buttons and the window background follow the same choice.
src/ui/Sheet.tsx is the only importer of the sheet library (@gorhom/bottom-sheet). The task sheet rests at peek, half or full; heights are fixed per task and window (sheet-model.ts), so loading content never moves it. Lists, stops and routes open at half, a place and the empty search peek, Privacy e fonti opens full. Drag, the header expand/collapse button and the handle (an adjustable control for TalkBack) move between the same snaps. Android Back lowers a sheet the user raised above its resting height, then unwinds the task stack. The header shows Close (to the map) and adds Back only when the task beneath is not the map. Camera padding follows the sheet's target height, re-centred on the camera's actual centre. When a short window gives two snaps the same height, the sheet library sees one detent and the logical snap stays consistent. The sheet is clipped above the navigation bar. Full sits just under the search bar. Content scrolls at full; at peek and half a content drag first raises the sheet (the library locks scrolling below the top snap). Every wrapper between the sheet and a scroller must be able to shrink (SHRINKING_FILL): the library sizes its content box after the first layout pass, and a plain flex: 1 wrapper keeps its content height, leaving nothing to scroll. Long lists use the sheet's virtualized list.
Build screens from src/ui: Button (primary, secondary, quiet), IconButton (48 dp, required label), ListRow, Chip and SegmentedControl, SectionHeader, SheetHeader, Notice (info, caution, danger, success; icon and wording, never colour alone) and TransitLineBadge. Line badges use the operator's route colour when supplied, with an AA text fallback, and distinct shapes and glyphs for metro, tram, bus and rail. GTT departures carry only line names, so only the metro (M1) is classified. Body text is 16 sp; departure times are larger tabular numerals. In a stop sheet, departures come first and saving is an icon action.
The app belongs to the avoid.quest family. Launcher name: avoid maps (development: avoid maps dev). Wordmark: maps.avoid.quest in Geist Mono, lowercase, in About within Privacy e fonti.
- Colour: pure black chrome (
chrome, the window, system bars and guidance bar) over near-black zinc surfaces. White is the only accent: the primary action is a white pill with black text. Light mirrors this with off-white surfaces and a black pill. Colour carries meaning only: signal green for live/verified, amber for caution and stale data, red for disruption and cancellations. Everything else is greyscale; transit line colours appear only on small badges. Every state keeps its text label. - Type: Geist Sans for UI text (16 sp body), Geist Mono with tabular figures for times, minutes, distances, stop codes and accuracy, and Mona Sans (heavy, letter-spacing about −0.04 em) for sheet titles, departure minutes and the next-turn distance. Use
Text,NumandDisplayfromsrc/ui; a test rejectsTextimported directly from React Native. Font scaling stays enabled. - Minimalism: hairline dividers instead of cards, few filled surfaces and no decorative shadows. Lists read like a departure board: badge or glyph, then name, then a right-aligned mono value.
- Live switches: pressable surfaces and dividers take colours inline from
useThemeColors()(src/ui/control-styles.ts,useHairlines()). Android did not repaint NativeWind colour classes onPressableafter a live scheme change. A test rejects colour classes on pressables andborder-divider. - Mark:
assets/brand/mark.svgadapts the avoid.quest sun disc cut by two horizon lines, bolder for launcher sizes.scripts/render-brand-assets.mjsrenders the icon, adaptive foreground, Android 13+ themed (monochrome) layer, splash icon and favicon reproducibly. The Android 12+ splash masks its icon to a circle, so the splash shows the mark only, on black.
Keep one map mounted across browsing, sheet expansion and navigation. Small inset task cards overlay that viewport at a compact height or an explicitly expanded height; keyboard resizing may reduce the sheet's available space while preserving the map. Status, loading and error updates change content inside reserved regions. Anchor route actions outside scrolling details, and keep navigation instruction, trip summary, Retry and Stop geometry independent of position quality.
Frame a planning route once for the requested origin, destination and mode, or when the user selects an alternative or requests the full route. Refreshes update its line without reframing. Panning consumes any pending frame so a late response respects the chosen view. Camera padding must leave visible map space on narrow, expanded and side-sheet layouts. Road guidance uses the first-person camera described in navigation: a gesture enters free at its start, Ricentra restores following in one move, and the overview button frames the remaining route once. Fixes and reroutes never take the camera back.
Keep current quality separate from retained coordinates. The native snapshot supplies the last accepted accuracy and current usability/problem, not the accuracy of rejected samples. Label retained numbers Ultima posizione accettata and paused maneuvers Ultima indicazione; keep their geometry while guidance is suspended. Provider selection and accuracy/age policy are separate concerns.
In Mezzi, alternatives are concise rows: departure–arrival in Geist Mono, line badges in boarding order with change markers (a walk glyph when the change is on foot), total walking, number of changes and one word-labelled timing state (cancellation in red, passed or unconfirmed times in amber; MATO predictions have no source timestamp and are never green). The selected alternative's timeline shows at once: access walk → board (stop, public code, direction, platform when supplied, expected and timetable time with provenance) → ride (intermediate stops when MATO supplies them) → alight → transfer walk … → arrival. Strictly validated GTT endpoints link to their stop boards. The anchored primary action is Cerca percorsi before alternatives exist and Segui viaggio afterwards; it needs no position fix.
Trasporti lists the nearest pilot rail stations above the GTT stops; a station opens a Transitous board with departures/arrivals, platforms as published, cancellations and the Dichiarato in tempo reale · aggiornamento origine non disponibile label. Metro-only stops say Solo orari programmati — tempo reale non disponibile. A stop board without GTT realtime offers Cerca su Transitous (see online services).
Road guidance is first-person: a flush banner in the chrome colour on top, the map with the puck low in the space between banner and strip, and a compact bottom strip.
- Banner: a maneuver glyph drawn from the OSRM type and modifier (straight, slight/normal/sharp turns, U-turn, fork, merge, ramps, roundabout with exit number and circulation, arrival; an unknown maneuver shows a neutral glyph with the supplied text, never a guessed turn), the distance in heavy Mona Sans with a smaller unit, then the street and the action in Geist with two lines reserved. A reserved row shows Poi … only when the following maneuver comes within about ten seconds of travel after the upcoming one; a roundabout exit number sits beside its glyph. Status (Ricalcolo del percorso…, Fuori percorso, reduced precision, Guida in pausa · Ultima indicazione, the search signal) floats in its own pill just below the banner, so a warning is never hidden by Poi; both are also in the banner's spoken label. Each banner row has a fixed height measured for the current font scale (text capped at 2×), so no instruction or status changes the banner height.
- Strip: arrival time labelled arrivo stimato, remaining time and distance senza traffico, the voice toggle (active, muted and unavailable are distinct icons and labels), overview and Interrompi. On narrow screens or with large text the summary takes its own row above the controls, so no label or number is truncated. Tapping the summary opens details. Riprova appears only beside an active problem, floating above the strip with Ricentra. A paused position never advances an apparently current arrival time: the strip shows Stima sospesa and labels the remaining values as the last estimate.
- Map: the remaining route in the brand ink with a contrasting casing, the travelled part thinner and muted, one cased arrow through the next junction from the real geometry, and the puck (a wedge with a live green centre, a disc when the direction is unknown, a subdued ring for a retained position). Driving and cycling hide generic business dots and labels but keep street names; driving shows one-way chevrons. From zoom 17 road guidance and transit walks (including a freely panned or paused road map) show approximate grey building volumes from mapped heights or floor counts; default-height buildings stay flat footprints. The route, junction arrow, puck and labels are drawn over buildings and never hidden behind them. Browsing, planning, overview at every zoom and transit rides stay flat.
Prioritize the next instruction, map, current problem and Stop action. Present recovery beside the problem. Keep voice status and setup in navigation details. Anchor the active transit confirmation beside Stop. Transit following has its own screen, not the road panel: the stage and instruction on top, the next boarding with its live provenance (or Corsa non confermata), the stop to get off at, journey age and passed/missed warnings, then the remaining timeline; the large confirmation sits beside Stop. Preserve transit confirmation controls and uncertainty when simplifying the layout. Route previews remain planning; native voice, position and background behavior require the separate navigation acceptance checks.
src/features/app/task-model.ts is the source of truth for which task owns the sheet: one root (map, search, Trasporti or Salvati), the detail tasks opened from it (place, stop, rail station, planner, journey stop) and Privacy e fonti on top. The sheet's back arrow closes the top task and returns to the task beneath with its context. Android Back first dismisses the keyboard and lets active guidance confirm Stop. Then it cancels origin picking as its own step, unwinds one task, and at a root collapses an expanded sheet before returning to the map. The reducer holds task choices: the selected place, stop and destination, and the planner's chosen origin with its step. Typed text, location requests and their status, fetched payloads and refresh timing stay in feature hooks.
Each feature under src/features/ exposes a hook and context with intent-level actions such as openPlace, openStop, beginRoute and startGuidance. Request controllers react to task transitions synchronously: a task moved behind another task suspends, and a closed or replaced planner resets. AppProviders composes features in dependency order; AppShell lays out the map, controls and sheet. Shared primitives live in src/ui/.
- Cold launch with authorized, denied and disabled location. Confirm the neutral map and accurate acquisition/failure states; verify no category selection, discovery pins or result sheet before an action. Repeat without a usable fix.
- Pan while location acquisition is pending. Confirm the user's chosen view remains stable, then use the location control to recenter explicitly.
- Open search, choose a category, type a place/address, select a result, and close or clear search. Confirm pins and sheets follow those actions and the idle map returns cleanly. Repeat with Android Back and the keyboard open.
- Open transport, saved places and route planning. Confirm each remains reachable, manual origin selection works without location, and relevant source/freshness information survives the compact layout.
- Replay navigating → inaccurate → stale → navigating, route loading → success → refresh failure, and expand/collapse. Compare map, sheet and primary-action bounds; asynchronous changes must not move them. Pan before a route response and after a result, then refresh; confirm the camera stays put. Verify explicit route framing and recentering still work.
- Inspect narrow screens, large text and screen-reader labels. Confirm search, recenter, back/close and navigation Stop remain reachable without covering required attribution. Record browser and device evidence separately.
- Switch Sistema/Chiaro/Scuro while browsing, with a route preview, and during navigation, then change the Android theme with Sistema selected. Confirm the map keeps its camera, route, markers and position, the system bars stay legible, and the choice survives a restart.