#18: [companion] Modernize the smartphone settings UI · anthodev/lapin-fute

🔢 Impact Version (SemVer)

MINOR

📝 Description

Modernize the Lapin Futé smartphone companion configuration interface to make it cleaner, more compact, and easier to navigate.

The current interface uses a light-only palette and permanently expanded settings sections. Each favorite places three action buttons on a full-width row below its name input. The About page needs clearer separation between subsection headings and body text. The primary token creation link currently opens documentation, and the page does not clearly explain that a personal PRIM token is required for live departures.

This ticket concerns the smartphone configuration interface only, not the smartwatch UI.

✅ Expected Behavior

Visual direction and system theme

Use the frontend-design skill before implementation to define a coherent visual direction grounded in Lapin Futé.
Make the interface cleaner and more modern through deliberate typography, spacing, colors, and control styling rather than additional decoration.
Support light and dark themes automatically following the smartphone preference through prefers-color-scheme, including changes while the page is open.
Apply the theme consistently to settings, About, form controls, feedback messages, disabled states, and the footer.
Preserve official transport line colors and pictograms.

Collapsible sections

Allow each main settings section to expand and collapse independently: PRIM access, Favorite departures, Add a favorite, and Watch synchronization.
Keep headings and an explicit expanded/collapsed indicator visible.
Preserve entered values and selections when collapsing or reopening a section.
Ensure validation errors cannot remain hidden inside a collapsed section.

Compact favorite actions

Reduce the space occupied by Move up, Move down, and Remove.
Prefer compact icon buttons to the right of the favorite name input where width permits, rather than a separate full-width button row.
Keep the name field usable and buttons comfortable to operate by touch.
Preserve disabled boundary actions for the first and last favorites.
Provide localized accessible action names and distinguish removal from reordering without relying on color alone.

Readable About page

Establish a clearer hierarchy between the page title, subsection headings, and paragraphs.
Increase separation between subsections while keeping each heading visually connected to its own text. Pay particular attention to heading-to-body spacing.
Improve font sizing, weight, paragraph spacing, and line height for long-form reading.
Preserve existing legal information, credits, links, and English/French content. A legal copy rewrite is outside this ticket.
Keep the return-to-settings action easy to find.

PRIM token creation and documentation links

Point the primary “Create a PRIM token” / “Créer un jeton PRIM” link to:
https://prim.iledefrance-mobilites.fr/fr/mes-jetons-authentification
This opens the token management/creation page rather than documentation. Authentication may be required by PRIM.
Keep the existing documentation URL available through a separate secondary link labeled “Instructions”:
https://prim.iledefrance-mobilites.fr/en/aide-et-contact/documentation/donnees-disponibles/api/generer-un-jeton-pour-acceder-aux-api
Distinguish documentation from the primary action, for example “Create a PRIM token (Instructions)”.
Open both links in a new tab with rel="noopener noreferrer" so users retain their configuration edits.

Explain why a PRIM token is required

Clearly state that a personal PRIM token is required to retrieve live departures.
When no token is configured, show the requirement next to the creation link and input instead of relying only on “No key is configured”.
Explain that users can browse stops and prepare favorites without a token, but cannot retrieve live departures.
Keep the missing-token requirement visible in the collapsed PRIM section summary.
Do not present a saved token as validated merely because it is present.

Suggested copy:

EN: “A personal PRIM token is required to retrieve live departures. You can prepare your favorites without one.”
FR: “Un jeton PRIM personnel est obligatoire pour récupérer les prochains départs en temps réel. Vous pouvez préparer vos favoris sans jeton.”

📋 [Feature] Acceptance Criteria

Settings and About consistently follow the smartphone light/dark preference, including changes while the page is open, without losing edits.
Each main settings section can be independently expanded and collapsed using touch or keyboard, with its state exposed to assistive technology.
Collapsing sections preserves draft values, favorite edits, and selections.
Validation errors inside collapsed sections make the relevant content and error visible.
Favorite actions use less vertical space than the current separate three-button row while remaining usable on narrow mobile screens.
Rename, move, and remove retain their behavior, including disabled movement at list boundaries.
Icon-only controls have meaningful localized accessible names and visible focus states.
About subsection headings are visibly distinct from body text, with stronger spacing between sections than within them.
Both languages remain usable at widths from 320 to 430 CSS pixels, including long stop names, destinations, and favorite labels.
No horizontal overflow or inaccessible content is introduced by collapsed sections, compact controls, or the fixed footer.
The primary token link targets https://prim.iledefrance-mobilites.fr/fr/mes-jetons-authentification; a distinct “Instructions” link opens the existing documentation URL.
Both external PRIM links use target="_blank" and rel="noopener noreferrer" and remain distinguishable in both languages and themes.
Without a configured token, the page explicitly explains that live departures require a personal PRIM token, including when the PRIM section is collapsed.
Users can still browse the catalog and prepare favorites without a token; no new blocking validation is introduced.
A configured token is not presented as verified unless an existing validation mechanism has confirmed it.
Before/after mobile screenshots demonstrate settings, favorite management, and About in both themes.

🔗 Affected Endpoints/Routes

Smartphone configuration page: packages/config-page/index.html.
Settings and About are views within the same page.
External PRIM destinations listed above.
No backend endpoint or API contract changes.

🧪 Tests to Add

Type	Coverage
Browser interaction / manual QA	Independent section expansion, retained edits, visible validation errors, keyboard access, accessible icon controls
Visual verification	Light/dark themes, live preference changes, English/French content, narrow mobile widths, long labels, About hierarchy, missing-token summary
Regression	Zero, one, and six favorites; rename/reorder/remove; existing key controls and Pebble save behavior
Link verification	Distinct PRIM creation and documentation destinations and labels, without creating a token or entering credentials
Targeted automated regression, where warranted	State-loss or hidden-validation edge cases introduced by collapsible sections, using existing project conventions

Reuse existing tooling. Do not introduce PHPUnit or Behat for this static JavaScript interface. Keep new automated tests focused on meaningful behavioral risks.

⚙️ Constraints

Apply the frontend-design skill when designing and implementing the UI.
Scope changes to smartphone presentation and interaction.
Preserve the six-favorite limit, configuration payloads, PRIM key handling, and Pebble save bridge.
Do not change smartwatch behavior, catalog access, or network request policies.
Follow the system theme without adding a persisted theme preference.
Preserve English/French localization and official transport branding.
Do not rewrite legal content as part of the visual redesign.
Compact controls must retain usable touch targets, sufficient contrast, and visible keyboard focus.
Missing-token guidance must not introduce network validation, new requests, or a requirement to provide a token before preparing favorites.

⚠️ Impact on Existing Behavior

Settings sections become collapsible, favorite actions become more compact, and colors follow the smartphone theme. The primary PRIM link opens token management instead of documentation, which remains available separately. Missing-token guidance explicitly explains the limitation on live departures.

Underlying configuration behavior remains unchanged. No data migration or protocol change is expected.

🔍 Technical Context

packages/config-page/index.html: settings sections; #about-view, #about-en, and #about-fr; #key-link currently targets documentation.
packages/config-page/styles/config-page.css: :root declares color-scheme: light; .favorite > input and .favorite-actions span the full grid width; .favorite-actions uses three equal-width columns. h3, .about-view p, and .about-heading control About typography and spacing. The footer has a hardcoded light background.
packages/config-page/src/config-page.js: renderFavorites() rebuilds rows and creates rename/move/remove controls; preserve draft and focus behavior. The add section is hidden at six favorites and must retain that rule. Extend existing localized element bindings for the secondary documentation link and required-token explanation.
packages/config-page/src/config-core.js: localized COPY.en / COPY.fr, including keyLink, and configuration state behavior.

Local preview:

npm run build:config-site
python3 -m http.server 8765 --bind 127.0.0.1 --directory var/config-site