GIS-iPad

Design Principles — iPhone Companion

Source

The iPhone companion is the same Meridian product on a smaller screen, not a separate app. The canonical design system remains Aero, defined in design_principles.md. This document records only the iPhone-specific adaptations of Aero. Where this file is silent, the iPad principles apply unchanged.

Recreate Aero natively in SwiftUI and MapLibre Native iOS, the same way the iPad and Mac surfaces do. The iPhone app is a universal-iOS build of the existing target, gated by a PlatformCapabilities.isPhone flag, not a fork.

Design Thesis On iPhone

The iPhone companion is a field-and-pocket viewer with light authoritative editing. It exists so a project authored on iPad or Mac can be opened from iCloud Drive, read in context, lightly corrected, annotated, and saved back — one-handed, in portrait, often outdoors.

It is deliberately narrower than the iPad app. The iPhone never tries to be a full GIS workspace. It does fewer things, and the few things it does must feel calm, certain, and reachable with a thumb.

Aero’s signature carries over intact:

Full-bleed live map canvas.
Floating frosted, grain-textured, accent-tinted glass.
A single teal-green accent (and the shared tint presets).
Monospaced numeric readouts for spatial data.
Adaptive light and dark appearances.

What changes is the chrome model: persistent side panels and the bottom tool dock become bottom sheets and a single compact action cluster. There is no drawing dock, because the iPhone has no geometry creation tools.

What The iPhone Deliberately Drops

The iPhone is scoped to viewing, basemap switching, map bookmarks, read-only tap-to-measure, attribute editing of authoritative features, text/callout notes, and saving back to iCloud with conflict detection. The following iPad/Mac surfaces are intentionally absent, and their chrome must not appear on iPhone:

Geometry drawing, vertex editing, snapping, the tool dock, and the contextual draw bar.
Layer reorder, opacity, style/symbology, labels, definition filters, locking, rename, delete, and metadata editing. Layers are visibility-only.
GeoJSON import, Open Data Library, OSM/Natural Earth/OGC providers, custom-URL basemaps, and PMTiles import (basemap switching among built-in online presets is allowed).
Spatial analysis, analysis history, and the field calculator.
Export, KML/WKT/CSV output, and PDF map layout.
Blank project creation and project duplication.
Multi-selection batch workflows.

If a feature is not in the iPhone scope, do not show a disabled control for it. Omit it. A quiet, smaller surface reads as intentional; a wall of greyed-out buttons reads as a broken iPad app.

Product Feeling

Calm, capable, spatial, immediate, trustworthy — the same five words as iPad, re-weighted for a phone in one hand:

Calm: the map fills the screen; chrome is a few floating glass elements and sheets that come and go. Nothing competes with the map.
Reachable: primary actions (save state, layers, note, feature inspector) sit within thumb reach near the bottom. The top edge carries identity and status, not frequent actions.
Spatial: coordinate readout, scale, compass, and pitch/north reset stay available; selection and dirty state stay visible.
Immediate: tapping a feature opens a bottom inspector instantly; saving an attribute edit gives clear local feedback before the iCloud publish.
Trustworthy: document state (downloaded, local draft, edited, conflict, unavailable) and unsaved-edit state are always legible. iCloud publish is explicit and never silently overwrites a newer remote copy.

Visual System On iPhone

Color And Materials

Unchanged from iPad. Use the same light/dark token sets and the same three-layer Aero glass (material + 1 px border + inner highlight + grain). Grain opacity stays slightly stronger in dark mode. Do not introduce phone-only accent colors.

Glass on iPhone is used more sparingly than on iPad because there is less screen to layer: reserve it for the top status pod, the bottom action cluster, bottom sheets, the coordinate chip, toasts, and the conflict sheet.

Typography

Use the same SF Pro / SF Mono split, with the iron rule intact: any number a user reads for spatial judgment uses SF Mono (latitude/longitude, zoom, scale, feature IDs, areas, counts, dates).

Scale type down one notch for the compact width:

Screen and project titles: 24 to 28 pt, heavy, tight tracking (iPad uses 30 to 32 pt).
Sheet titles: 17 to 20 pt, semibold to bold.
Section labels: 12 to 13 pt, uppercase, bold.
Body and controls: 15 to 16 pt, medium — slightly larger than iPad’s 14 pt because the phone is held closer and tapped with a thumb.
Small metadata: 12 to 13 pt.

Respect Dynamic Type. Sheets, the project library, and the attribute form must remain usable at the larger accessibility text sizes; prefer reflow and scrolling over truncation.

Shape, Spacing, And Touch

Radii inherit from Aero (cards 20 pt, large sheets 26 pt, small controls 11 to 14 pt, pills 16 to 24 pt). The bottom sheet uses the 26 pt top-corner radius like the iPad table sheet.

Touch targets get more generous on iPhone, not less:

Primary buttons: 48 pt tall (iPad 46 pt).
Icon buttons: 44 pt minimum, 46 to 48 pt preferred for the bottom action cluster.
Navigation and list rows: at least 48 pt.
Layer visibility rows: at least 48 pt with the eye toggle as a full-height tap target.

Never ship an interactive control below 44 pt. There is no Apple Pencil precision path on iPhone, so map hit-test tolerance for tapping features should be tuned for a fingertip (larger than the iPad Pencil tolerance).

Layout Principles On iPhone

Map First, Chrome Floating

Same as iPad: full-bleed MapLibre canvas, chrome floating above it, geographic context always visible. The difference is density — far fewer simultaneous elements.

Persistent on the map at rest:

Top: compact status pod (back, project name, document/save state).
Bottom: compact action cluster (layers, add note, and — when a feature is selected — the feature inspector entry).
Bottom-left: coordinate readout.
Bottom-right: navigation cluster (scale, compass with north/pitch reset, optional zoom).
A single global Save to iCloud affordance that surfaces dirty state.

Everything else is a sheet that the user summons and dismisses.

Sheets Replace Panels

The iPad’s leading layer panel, trailing inspector, and bottom table become iPhone bottom sheets:

Layers → a bottom sheet of visibility toggles.
Feature inspector → a compact bottom inspector (medium detent) that can expand to the full attribute form.
Attribute form → a large/full-height sheet.
Conflict resolution → a focused modal sheet.

Use system sheet detents (medium / large) so sheets feel native and one-handed. Only one primary sheet is presented at a time; opening a new one replaces the conflicting one rather than stacking, mirroring the iPad “panes replace, never stack” rule.

Portrait First, Landscape Supported

The iPhone’s primary orientation is portrait (the iPad’s is landscape). Support landscape, but optimize reach and sheet sizing for portrait. Honour the safe-area and home indicator: keep the bottom action cluster and sheet grips clear of the indicator, and keep map controls inside the safe area.

Visible State, Compacted

The same states must stay visible without digging, but compacted:

Selected feature.
Layer visibility / hidden layers (inside the layers sheet).
Unsaved edits and document state (top status pod + Save affordance).
Coordinates, zoom, scale, compass, and pitch.

Use the accent consistently for selected and active states. Use distinct, non-color-only treatment for document states (downloaded / local draft / edited / conflict / unavailable) so they survive VoiceOver and colorblind use.

Interaction Principles On iPhone

The iPhone adds pitch to the navigation model. “Orbit” means bearing plus pitch around the map center — not 3D terrain.

One- and two-finger gestures pan, pinch-zoom, two-finger rotate (bearing), and two-finger vertical drag to tilt (pitch).
Pitch defaults to 0 and is clamped to a comfortable maximum.
The compass control rotates to show bearing; tapping it resets bearing to north, and a pitch-reset affordance returns pitch to 0 (flat). Make “return to flat north” a single, obvious recovery action — users tilt by accident on phones.
Camera (center, zoom, bearing, pitch) is persisted locally with the working copy and included on explicit publish. Camera-only browsing must not trigger a scary unsaved-work prompt. PDF/layout snapshots remain top-down regardless of pitch.

Selecting And Editing Attributes

Tapping the map hit-tests visible authoritative layers only (markup/notes are non-authoritative and are not attribute-editable here).
A hit opens the bottom feature inspector: title, geometry summary, and key fields.
Expanding opens the phone-optimized attribute form. Saving the form creates a local UpdateProperties edit-session change — it does not publish to iCloud by itself.
Hidden or locked layers do not offer attribute editing; surface the reason calmly.
Editing is attributes-only. There is no geometry move/add/delete on iPhone.

Notes (Non-Authoritative Markup)

The note action adds text point notes and callout notes only, reusing the existing markup layer path (createMarkupLayer / addMarkupItem / updateMarkupItem).
Markup stays non-authoritative and excluded from analysis/export rules.
Freehand, arrows, shapes, and geometry editing remain deferred — do not surface them.

Saving, Dirty State, And Conflicts

Saving to iCloud is the iPhone’s most consequential action and gets the most design care.

Layer visibility changes, attribute edits, and notes mark the document as needing publish.
A single Save to iCloud affordance commits the local edit session and publishes the package. It must clearly show dirty vs clean state.
Publishing must never silently overwrite a newer remote copy. Before publishing, the app re-checks the source revision/fingerprint. If the remote changed, present a calm conflict sheet with three explicit choices: reload the iCloud version, save the phone working copy as a conflict copy, or cancel and keep editing locally. No last-writer-wins, no automatic merge in v1.
Document availability is a first-class state: show downloading, not-yet-downloaded, and iCloud-unavailable states honestly rather than failing silently.

Motion

Inherit Aero motion (200 to 260 ms eases, ~2.5 s toasts). Prefer native sheet present/dismiss animations and detent transitions. Avoid motion that drops map frames during pan/zoom/tilt.

Accessibility And Responsiveness

Accessible labels for every icon-only control (layers, note, compass/pitch reset, save, zoom, back).
Dynamic Type support across the project library, sheets, inspector, and attribute form.
VoiceOver labels for selected feature, layer visibility, document state, dirty state, and conflict choices.
Sufficient contrast for text and chips over both light and dark maps.
Do not rely on color alone for selection, dirty, document-state, or conflict states.
Portrait and landscape both verified; safe-area and home-indicator respected.

Implementation Notes

Universal iOS build of the existing target: TARGETED_DEVICE_FAMILY = "1,2", with iPhone orientations added and iPad/Mac behavior unchanged.
Phone routing is selected in AppRootView via PlatformCapabilities.isPhone; the iPhone uses PhoneProjectLibraryView, PhoneWorkspaceView, and a narrow PhoneWorkspaceModel, not the full iPad WorkspaceView surface.
Reuse the shared design tokens, Aero glass component, and the existing services (markup, update-properties edit session, document coordinator). The iPhone is new views over shared state, not new geometry/storage logic.
For substantial iPhone UI work, run taste, impeccable, and grill-me (or the repo-local fallbacks in skills/) before implementing, per AGENTS.md.