System Requirements Document for address-list-map

1. Introduction

address-list-map is a compact, responsive address book that pairs a scannable saved-address list with a single live map. Every saved address appears as one line of type containing exactly three facts — Name, Mobile Number, and Full Address — and every saved address also appears as a marker on one map displayed beside the list. Selecting an address row highlights the corresponding marker and centers the map on that location, so the list and the map always agree about which place is in focus.

The product intent is a working instrument, not a marketing surface: a person checking a name, a number, and a full address at a glance, then finding that same person on a map. The audience is anyone who keeps a list of places — couriers, small-business owners, families, operations staff — working on desktop and on a phone, who need the layout to stay clean, compact, and easy to scan in both contexts.

2. System Overview

The current delivery is a first-party custom UI with two pages: an anonymous Landing page that presents the address list and map experience as a full-viewport instrument, and the Address List working view that contains the saved address list, the adjacent map, all address markers, and the selection synchronization between them. Both pages are reachable without an account; no sign-in, registration, or permission model is part of the accepted scope.

The single active human actor is the Address List User, who reads the list, selects an address, and observes the map respond. The map tile provider is a non-persona external actor that supplies the base map imagery; the application owns the list, the marker set, the selection state, and the camera behavior.

Accepted behavior in scope: a responsive address list where each address is one line of Name, Mobile Number, and Full Address; all saved addresses rendered as markers on one map beside the list; click-to-select that highlights the matching marker and centers the map on that location; and a layout that stays clean, compact, and scannable on desktop and mobile.

Narrow exclusions: no address creation, editing, or deletion workflow is accepted; no search, filter, sort, or grouping of addresses is accepted; no routing, directions, or turn-by-turn navigation is accepted; no multi-map, split-map, or per-address map view is accepted; no accounts, roles, or permission controls are accepted; no marketing hero, illustration, or stock photography is accepted.

2a. Product Interpretation and Delivery Boundary

The product is delivered entirely as first-party application pages. The Landing page is an anonymous entry surface that shows the instrument itself — a ruled header, a populated address list plate, and a map plate with the first address pre-selected — so a visitor immediately understands what the tool does before entering the working view. The Address List page is the working view where the list scrolls against a stationary map on desktop and against a pinned map plate on mobile.

Access is anonymous on both pages. The accepted requirements describe viewing and selecting saved addresses; they do not describe a private, resumable, or per-person state that must be bound to an identified owner, so no identity establishment, verification, or account management is introduced. The map base imagery is owned by an external map tile provider; the application owns the list, the markers, the selection state, and the camera movement.

Everything described in this document is current. No future-horizon capability has been accepted, and nothing in the current pages depends on one.

2c. Page Content and Component Coverage

Landing

• Information and state: A full-viewport instrument composition. A thin ruled header bar carries the wordmark ADDRESSES in Archivo 700 uppercase at 13px with +0.14em tracking on the left, a live count in tabular figures (for example 24 SAVED) on the right, and a 3px orange segment under the rule. Below the header, an asymmetric two-plate composition fills the remaining height: the left plate is the address list already populated and scannable, the right plate is the map with all markers and the first address pre-selected in orange. The largest type on the page is the 64px desktop / 40px mobile display line set flush-left in the left plate's header — Every place you keep. — in graphite Archivo 700 with tight leading, sitting directly above the tabular column labels.
• Primary action: Enter the working view to browse and select addresses.
• Supporting actions: Read the saved-address count; scan the pre-populated list rows; observe the pre-selected marker on the map plate.
• Domain entities: Saved address (Name, Mobile Number, Full Address, geographic coordinates, list index), address collection, map marker, selection state.
• Component responsibilities: Ruled instrument header (wordmark, live tabular count, orange underline segment); display headline block; left list plate with the three tabular column labels NAME / MOBILE / ADDRESS and one-line rows; right map plate with indexed circular markers and one active orange marker; entry control into the working view.
• States:
  • Loading: The map plate shows its warm-grey plate frame with a subdued placeholder surface while base tiles resolve; the list plate renders its rows immediately from saved data.
  • Empty: When no addresses are saved, the list plate shows the column labels and a single muted line stating that no addresses are saved yet; the map plate shows the base map with no markers and no active selection.
  • Success: The list plate shows populated one-line rows and the map plate shows one marker per saved address with the first address pre-selected in orange.
  • Error: If base map tiles fail to load, the map plate keeps its 1px #D8D3C8 border and shows a muted inline notice that the map is unavailable, while the list plate remains fully readable and selectable.
  • Recovery: The map plate offers a retry that re-requests base tiles; the list and its selection state are unaffected.

Address List

• Information and state: The responsive working view. On desktop, a fixed 4-column modular grid inside a 1280px max width: the left column (5 of 12) is the address list with a header row of three tabular labels and one-line rows on a strict baseline grid; the right column (7 of 12) is the map plate, sticky and full viewport height minus the header, so the list scrolls against a stationary map. On mobile, the same grid collapses to a single column: a compact map plate pinned under the header at 38vh, the list scrolling beneath it, and each row becoming a two-line block (name + number on line one, address on line two) while keeping the same tabular rhythm. The header is a thin ruled bar: wordmark left, address count and an Add address control right.
• Primary action: Select an address row to highlight its marker and center the map on that location.
• Supporting actions: Read each row's Name, Mobile Number, and Full Address; expand the selected row's detail strip to reveal the full untruncated address with copy and route controls; hover a row to preview its marker with a 1px orange ring; scroll the list against the stationary map.
• Domain entities: Saved address (Name, Mobile Number, Full Address, geographic coordinates, list index), address collection, map marker, active marker, selection state, map camera position and zoom.
• Component responsibilities: Ruled instrument header (wordmark, live tabular count, Add address control, orange underline segment that slides to sit above the active list column); tabular list header with NAME / MOBILE / ADDRESS labels; one-line address rows with a 3px orange left rule and faint warm tint when selected; the 28px detail strip on the selected row; the sticky map plate with 1px border, 6px radius, and one soft low shadow; indexed circular markers with graphite rings and the active marker in solid orange with a white ring.
• States:
  • Loading: Rows render from saved data as soon as it is available; the map plate shows its framed placeholder surface until base tiles resolve, and markers appear as their coordinates are known.
  • Empty: With no saved addresses, the list shows the tabular column labels and a muted line stating that no addresses are saved yet; the map shows the base map with no markers, and no row is selected.
  • Success: Every saved address appears as exactly one row and exactly one marker; the selected row carries the orange left rule and warm tint, its detail strip is expanded, its marker is solid orange with a white ring at 1.15 scale, and the map camera has panned and zoomed to that location.
  • Error: If base map tiles fail, the map plate retains its border and shows a muted inline notice that the map is unavailable while the list stays fully readable and selectable; if an address has no usable coordinates, its row still renders with Name, Mobile Number, and Full Address and its marker is omitted, with a muted inline note on the row that the location cannot be mapped.
  • Recovery: A retry on the map plate re-requests base tiles and restores markers and camera behavior; selecting a different row always re-establishes a consistent selection and camera position.

3. Functional Requirements

FR-1 — Responsive address list UI (explicit) As an Address List User, I should see a clean, responsive address list UI so that I can read my saved addresses comfortably on desktop and on mobile.

• Trigger/input: Opening the Address List page.
• Observable result: The list renders in the desktop two-plate grid (list left, map right) at desktop widths and in the single-column stacked layout (map plate pinned at 38vh under the header, list scrolling beneath) at mobile widths.
• Access state: Anonymous; no sign-in required.
• Failure/recovery: If the viewport is resized across the breakpoint, the layout reflows without losing the current selection or the map camera position.
• Continuation: The user reads rows and selects an address.
• Provenance: explicit.

FR-2 — One-line address rows with Name, Mobile Number, and Full Address (explicit) As an Address List User, I should see each address displayed in a single line containing the Name, the Mobile Number, and the Full Address so that I can scan the list quickly.

• Trigger/input: The saved address collection is rendered.
• Observable result: Each address occupies exactly one line on desktop with the name in 600 weight, the mobile number in tabular figures, and the address truncated with an ellipsis; on mobile the same row becomes a two-line block with name and number on line one and the address on line two, preserving the tabular rhythm.
• Access state: Anonymous.
• Failure/recovery: A long address is truncated with an ellipsis rather than wrapping or breaking the row; the full untruncated address is revealed in the row's detail strip when the row is selected.
• Continuation: The user selects a row to reveal the full address and act on the map.
• Provenance: explicit.

FR-3 — All saved addresses as markers on one map beside the list (explicit) As an Address List User, I should see all saved addresses as markers on one map displayed beside the address list so that I can see where my saved places are.

• Trigger/input: The Address List page loads with saved addresses.
• Observable result: One map plate is displayed beside the list, and every saved address with usable coordinates appears as exactly one indexed circular marker on that single map.
• Access state: Anonymous; base map imagery is supplied by the external map tile provider.
• Failure/recovery: If base tiles fail to load, the map plate keeps its border and shows a muted inline notice that the map is unavailable; the list remains fully readable and selectable, and a retry re-requests tiles. If an address has no usable coordinates, its row still renders and its marker is omitted with a muted inline note on the row.
• Continuation: The user selects an address to focus its marker.
• Provenance: explicit.

FR-4 — Clicking an address highlights the corresponding marker (explicit) As an Address List User, I should have the corresponding location marker highlighted when I click an address so that I can see exactly which marker belongs to the row I chose.

• Trigger/input: The user clicks (or taps) an address row.
• Observable result: The selected row gains a 3px orange left rule and a faint warm tint; its marker flips to solid #D9540E with a white ring and scales from 1.0 to 1.15, settling in 140ms; the previously active marker returns to its graphite-ringed puck state.
• Access state: Anonymous.
• Failure/recovery: If the selected address has no usable coordinates, the row still shows its selected state and the map shows a muted inline note that the location cannot be mapped; selecting another row clears the condition.
• Continuation: The map camera moves to the selected location.
• Provenance: explicit.

FR-5 — Clicking an address centers the map on that location (explicit) As an Address List User, I should have the map centered on that location when I click an address so that the selected place is brought into view.

• Trigger/input: The user clicks (or taps) an address row whose coordinates are known.
• Observable result: The map performs a single smooth 400ms pan/zoom so the selected location is centered in the map plate; this is the only eased motion in the product.
• Access state: Anonymous.
• Failure/recovery: If base tiles are unavailable, the camera move is deferred and applied once tiles recover; if the address has no usable coordinates, no camera move occurs and the row's muted inline note explains why.
• Continuation: The user reads the centered marker, expands the detail strip, or selects another address.
• Provenance: explicit.

FR-6 — Clean, compact, scannable layout on desktop and mobile (explicit) As an Address List User, I should get a layout that stays clean, compact, and easy to scan on both desktop and mobile so that the list and map remain usable at any size.

• Trigger/input: Rendering the Address List page at any supported viewport.
• Observable result: Desktop uses a fixed 4-column modular grid inside a 1280px max width with the list at 5 of 12 columns and a sticky full-height map plate at 7 of 12; mobile collapses to one column with a 38vh pinned map plate and two-line rows; hairline 1px #D8D3C8 rules separate every row and panel edge, and no card shadows or decorative elevation appear except the single soft low shadow under the map plate.
• Access state: Anonymous.
• Failure/recovery: At intermediate widths the grid reflows to the nearest supported arrangement without horizontal scrolling or clipped rows.
• Continuation: The user continues scanning and selecting.
• Provenance: explicit.

FR-7 — Row detail strip for the selected address (required_inference) As an Address List User, I should see the full untruncated address and its copy and route controls on the selected row's detail strip so that truncation in the one-line row never hides the address I need.

• Trigger/input: Selecting an address row.
• Observable result: The selected row expands by exactly one 28px detail strip revealing the full address text plus 16px line pictogram controls for copy and route, drawn at 1.5px stroke in graphite.
• Access state: Anonymous.
• Failure/recovery: If clipboard access is unavailable, the copy control reports the failure inline without collapsing the strip; the full address text remains visible.
• Continuation: The user copies the address, opens a route, or selects another row, which collapses the previous strip.
• Provenance: required_inference — the explicit single-line constraint requires truncation, and the explicit full-address fact requires a place where the untruncated value is readable.

FR-8 — Hover preview of a row's marker (required_inference) As an Address List User, I should see a hover preview of a row's marker so that I can confirm which marker a row belongs to before committing to a selection.

• Trigger/input: Pointing at an address row on a pointer device.
• Observable result: The corresponding marker gains a 1px orange ring; moving away removes the ring; the active marker's solid orange state is unaffected.
• Access state: Anonymous.
• Failure/recovery: On touch devices without hover, the preview is simply absent and selection remains the only state change.
• Continuation: The user clicks the row to make the selection permanent.
• Provenance: required_inference — the explicit highlight-and-center behavior needs a non-committing way to associate a row with its marker when the list is long.

FR-9 — Live saved-address count in the header (required_inference) As an Address List User, I should see a live count of saved addresses in the header so that I know how many places the list and map are showing.

• Trigger/input: The saved address collection is loaded or changes.
• Observable result: The header shows the count in tabular figures (for example 24 SAVED) and updates whenever the collection changes.
• Access state: Anonymous.
• Failure/recovery: While the collection is still loading, the count shows a muted placeholder rather than a stale or invented number.
• Continuation: The user reads the count and continues scanning the list.
• Provenance: required_inference — the explicit "all saved addresses" constraint needs an observable statement of how many addresses are in scope.

FR-10 — Add address control in the header (required_inference) As an Address List User, I should see an Add address control in the header so that the list can grow beyond the addresses already saved.

• Trigger/input: The user activates the Add address control in the ruled header.
• Observable result: The control is present and reachable in the header on both desktop and mobile.
• Access state: Anonymous.
• Failure/recovery: No address-creation workflow is accepted in the current scope; the control must not present a broken or misleading flow, and any activation that cannot complete must report that plainly rather than silently failing.
• Continuation: The user returns to scanning and selecting addresses.
• Provenance: required_inference — the explicit "all saved addresses" constraint presumes a saved collection that can be added to; no creation workflow is specified, so none is defined here.

4. User Personas

Address List User

Product context. The Address List User keeps a list of saved places — delivery destinations, customer sites, family addresses — and needs to check a name, a mobile number, and a full address at a glance, then find that same person on a map. They work on desktop at a desk and on a phone in the field, often in a hurry, and they treat the tool as an instrument rather than a destination to browse.

Primary goal. Read the saved address list quickly and confirm where a specific saved place is on the map.

Distinct accepted responsibilities.

• Scanning the one-line rows, each carrying exactly Name, Mobile Number, and Full Address, and reading the tabular columns down the list.
• Selecting an address row to make it the active address.
• Reading the resulting highlight on the corresponding marker and the map camera settling on that location.
• Expanding the selected row's detail strip to read the full untruncated address and use its copy and route controls.
• Hovering rows to preview which marker belongs to which row before committing to a selection.
• Reading the live saved-address count in the header.
• Working the same list and map on desktop and on mobile without losing their place.

Relevant inputs and decisions. Which row to select; whether the truncated address in the row is enough or the detail strip is needed; whether to copy the address or open a route; whether to move on to another address.

Interactions with other accepted participants. The Address List User is the only active human actor. Their work depends on the external map tile provider, which supplies the base map imagery the markers sit on; the application owns the list, the markers, the selection state, and the camera movement, so the user never negotiates with the provider directly.

Observable success. The selected row carries the orange left rule and warm tint, its detail strip is expanded, its marker is solid orange with a white ring at 1.15 scale, and the map has panned and zoomed so that location is centered — with the list and map never disagreeing about which address is active, on either desktop or mobile.

5. Core User Flows

Flow 1 — Landing on the instrument and entering the working view

1. The Address List User opens the application and lands on the Landing page. No sign-in is requested.
2. The ruled header renders: ADDRESSES in Archivo 700 uppercase at 13px with +0.14em tracking on the left, the live count in tabular figures on the right, and the 3px orange segment under the rule.
3. The left plate renders the address list already populated and scannable, with the 64px desktop / 40px mobile display line Every place you keep. flush-left above the NAME / MOBILE / ADDRESS column labels.
4. The right plate renders the map with all markers, and the first address is pre-selected in orange.
5. The user enters the working view and arrives on the Address List page with the same list, the same markers, and the same selection.
6. If base map tiles have not resolved, the map plate shows its framed placeholder surface and the list stays fully readable; when tiles resolve, markers appear and the pre-selected marker is highlighted.
7. If no addresses are saved, the list plate shows the column labels and a muted line stating that no addresses are saved yet, and the map shows the base map with no markers.

Flow 2 — Scanning the saved address list

1. On the Address List page, the Address List User reads the tabular header NAME / MOBILE / ADDRESS.
2. Each saved address appears as exactly one line: the name in 600 weight, the mobile number in tabular figures so the column aligns down the list, and the address truncated with an ellipsis.
3. On mobile, the same rows render as two-line blocks — name and number on line one, address on line two — keeping the same tabular rhythm, with the map plate pinned at 38vh under the header.
4. The user reads the live count in the header to confirm how many addresses are in scope.
5. If an address has no usable coordinates, its row still renders with Name, Mobile Number, and Full Address and carries a muted inline note that the location cannot be mapped.
6. The user continues to selection.

Flow 3 — Selecting an address, highlighting its marker, and centering the map

1. The Address List User clicks (or taps) an address row on the Address List page.
2. The row's orange left rule snaps in and its background shifts to a faint warm tint in a 120ms linear state change.
3. The row expands by exactly one 28px detail strip revealing the full untruncated address plus the copy and route pictogram controls.
4. The corresponding marker flips to solid #D9540E with a white ring and scales from 1.0 to 1.15, settling in 140ms; the previously active marker returns to its graphite-ringed puck state.
5. The map performs a single smooth 400ms pan/zoom so the selected location is centered in the map plate — the only eased motion in the product.
6. The user reads the centered marker and the full address in the detail strip, and may copy the address or open a route from the strip.
7. If the selected address has no usable coordinates, the row still shows its selected state and the map shows a muted inline note that the location cannot be mapped; selecting another row clears the condition.
8. If base map tiles are unavailable, the camera move is deferred and applied once tiles recover; the list remains fully readable and selectable throughout, and a retry on the map plate re-requests tiles.
9. The user selects another address, which collapses the previous detail strip and repeats steps 2–5 for the new selection, or ends the session.

Flow 4 — Previewing a marker before committing

1. On a pointer device, the Address List User points at an address row without clicking.
2. The corresponding marker gains a 1px orange ring, confirming which marker belongs to that row.
3. The user moves the pointer away and the ring is removed; the active marker's solid orange state is unaffected.
4. On a touch device without hover, this preview is simply absent and the user proceeds directly to selection.
5. The user clicks the row to make the selection permanent, continuing into Flow 3.

Flow 5 — Working the list against a stationary map on desktop

1. On a desktop viewport, the Address List User sees the fixed 4-column modular grid inside a 1280px max width: the list at 5 of 12 columns on the left, the map plate at 7 of 12 columns on the right.
2. The map plate is sticky and holds the full viewport height minus the header, so the user scrolls the address list while the map stays stationary.
3. The user scrolls to a row further down the list and selects it.
4. The row highlights, its detail strip expands, its marker becomes solid orange, and the map camera pans and zooms to center that location while remaining in place.
5. The user continues scrolling and selecting without the map ever leaving the viewport.

6. Visuals, Colors, and Theme

The muse is Dieter Rams, and the headline is "Less, but better — one signal orange on honest grey." The direction is authoritative for this section.

Colour tokens (light mode).

Accent rationing is strict: the selected row's left rule and index chip, the active map marker, focus rings, and the one primary action. No blue, indigo, or violet appears anywhere in the palette.

Contrast. #1C1B18 on #F7F5F0 ≈ 15:1. White text on #D9540E ≈ 4.6:1, used only at ≥16px semibold. #8C877C is used only for 11–12px uppercase labels on #F7F5F0 (≈ 4.6:1).

Typography. Headings use Archivo at 600/700 with tight tracking (−0.02em), uppercase for section labels and the wordmark, sentence case for the display headline. Headline