# Agreed visual requirements for the production redesign Updated: 2026-09-23. Owner: Yaya. Yaya explicitly requested that the visual refinements made in the wireframe be logged and carried into the actual frontend redesign. This is the current decision record, not a list of every experiment. Read it before implementing activities 04 (overall UX) and 07 (visual refresh), and alongside the feature requirements in PROJECT-TODO.md. Do not treat earlier screenshots or historical handoff notes as overriding this record. Implementation is deferred until work on the real redesign is requested. These requirements are implemented in the local prototype, not yet in production. No tracker activity is complete on the strength of prototype work. ## Accepted layout and interaction decisions | ID | Requirement to carry into real code | Current wireframe reference | | --- | --- | --- | | V01 | Use the established monochrome direction: #0a0a0a, #fafafa, neutral borders, plain typography and left-aligned text. Preserve the recognisable site character. | wireframe/style.css | | V02 | Use the available viewport width with consistent navigation/content edges. The final requested side padding is twice the original: clamp(40px, 6vw, 128px) on desktop, 32px at widths up to 760px. | --page-gutter; main; .site-header | | V03 | Keep primary content and actions comfortably in the first fold where practical. Use compact headers, forms and summaries. Do not shrink text, clip expanded content or force all mobile content into one screen. | Compact task layouts in style.css | | V04 | Vertically center the main content in the available space between navigation and footer when it fits. Taller pages and expanded content scroll naturally. | main flex layout | | V05 | For adjacent panels in the same row, stretch the shorter panel to the tallest panel's content-driven height. Use layout sizing, not hardcoded heights. Recalculate naturally when errors or details appear; when panels stack on phones, each has its natural height. On the eSIM overview, the stacked middle cards share the total height and bottom edge of the single balance and home-screen cards. An unboxed landing introduction is not a panel to artificially enlarge. | .layout / .grid; grouped installation sidebar | | V06 | Keep Top up balance, Renew number and Bulk orders beside the top-left logo on desktop. Put How it works immediately after Buy eSIM in the right-hand main navigation and phone menu, linking to the second homepage section. On mobile layouts, hide these header quick links; they remain accessible in the full-screen mobile menu. Preserve normal navigation and keyboard/touch access. | index.html .site-header / .quick-links | | V07 | Keep the main header sticky. Pin private eSIM navigation directly beneath it, outside vertically centered page content. Measure actual header height so open phone menus and responsive wrapping do not overlap the tabs. Keep active-tab indication and horizontal touch/trackpad scrolling. Remove private tabs on public routes. | #esim-navigation; updateNavigationHeights; orderNav | | V08 | Present all four existing payment methods: Bitcoin, Lightning, Monero and Altcoins (Trocador, including the USDT route). Carry the selected method through checkout, resume and receipts for purchase, top-up, renewal and bulk. Keep network-fee display in the BTCPay invoice, as confirmed by Yaya. Explain any plan/credit minimum adjustment before checkout. | paymentMethods; invoice and transaction rendering | | V09 | Put Pay with buttons in a single horizontal row throughout checkout. On narrow screens, keep a readable, touch/trackpad-scrollable row instead of wrapping to two rows or overflowing the whole page. Retain descriptive accessible names and focus visibility. | .payment-methods | | V10 | Use an inset square action button for appropriate identifier-field utilities; keep space for the text, an accessible name, visible focus and a touch-sized target. The prototype's Use sample details fills the field without submitting, clears stale errors and returns focus to the editable value. Hardcoded demo identifiers remain prototype/test data; do not silently fill real customer fields with them. | .input-with-action; .field-action; sample-details handler | | V11 | Keep the compact plan choices, visible starting credit and price breakdown beside payment. Contextual management, top-up and renewal must keep the intended eSIM/number visible. Preserve the three-column desktop order overview and responsive stacking as the current baseline. Remove the redundant Order another eSIM and Get help with this eSIM links below its home-screen card; the main navigation still provides buying and help. | buy; orderPage; maintenance | | V12 | Preserve the agreed action wording: Buy eSIM, Coverage & rates, Manage eSIM, Help, Top up balance, Renew number, eSIM ID (IMSI), Save your private eSIM link, and state-specific payment/preparation checks. Refer to Proposal for the complete wording table and recovery states. | proposal.html#labels; wireframe/app.js | ## Private-link copy confirmation — 2026-09-23 Show “Copied” inside the Copy private link button after clipboard success, rather than a separate confirmation underneath. Keep the manual-copy fallback on failure. Apply this to both the order overview and payment page. ## Checkout fee clarification — 2026-09-23 At Yaya's request, removed the invented “Demo fees $0.00” row. The prototype price summary now contains eSIM price, starting credit and total. Do not reintroduce a generic zero-fee line during high-fidelity work or production transfer. The existing home/bulk frontend does fetch `/api/v1/fee` for a Bitcoin network-fee notice; this is not evidence of a universal zero fee or a generic checkout fee row. Yaya confirmed that the network fee is shown in the BTCPay invoice and that this is sufficient. Keep it there; do not duplicate it as a separate fee row in our checkout or add a new fee-disclosure step during the redesign. ## Feature directions that these layouts must accommodate Read [Account data notes](ACCOUNT-DATA-NOTES.md) for Yaya's supplied SMS/usage shapes. Messaging is inbound only. Do not assume handset delivery from `delivered`, invent a usage currency/timezone, or label binary usage totals as decimal MB/GB. - Direct iOS/Android setup starts native confirmation; keep visible QR/manual alternatives. Do not infer installation success from a tap or browser return. - Private order-page PWA/home-screen access supports returning to the correct eSIM for top-ups and new purchases. Keep web-app installation distinct from eSIM setup. - Spending, incoming messages, TOTP and payment recovery remain separately tracked features. Their prototype screens are not proof of API, security or device support. - Keep payment, order, installation and copy errors actionable without erasing context. Layout must grow naturally for recovery messages and expanded details. ## Explicitly superseded experiments Yaya requested a rollback to the state immediately after vertical centering. Do not restore the later forced equal-half landing split, centered/narrowed blocks in every column, centered text, or the proposed wholesale page-by-page relayout. Those were rolled back. Side padding/header alignment, pinned navigation, payment rows and equal-height adjacent panels were requested afterwards and ARE current. The landing baseline remains its original compact 1 : 1.15 grid, with left-aligned intro text. Equal panel heights do not imply equal column widths. Print / Save PDF was removed from the local UX documents. Wireframe launch tabs, prototype controls, simulated payments/security/native setup, sample credentials and dummy CSV output are review tools, not requirements to ship demo functionality. ## Agreed workflow: prototype → high fidelity → sign-off → production Yaya confirmed this sequence on 2026-09-23. Continue developing the separate prototype first. Yaya will work up the wireframe into high-fidelity designs and obtain design sign-off before production integration is requested. This does not start implementation in the real app or authorise a commit, push or merge. ### Make the high-fidelity prototype reusable - Stay with the existing HTML/EJS-compatible markup, plain CSS and vanilla JS modules. Do not introduce a framework or styling system requiring a migration. - Before substantial high-fidelity implementation, separate the current monolithic prototype stylesheet/renderers into reusable foundations, components and page layouts. Give spacing, colour, typography and sizing shared CSS custom properties. Keep original approved values traceable to V01–V12. - Keep real asset files, fonts and reusable component markup with the prototype. Use consistent semantic classes and documented variants for navigation, panels, form fields, payment actions, statuses and receipts. Avoid prototype-only IDs or global overrides as the basis of the final styles. - Separate presentation from mock data/actions. Define the data each view needs, using existing real fields/contracts where known. Include loading, empty, long content, errors, partial/unknown payments and multiple-eSIM cases. Do not base the finished design only on the short sample content. - Keep the prototype isolated while it evolves. Record each approved component's destination in the production code so styles/assets and markup can be transferred deliberately. The current hash router, sessionStorage transaction simulator, fake authenticator, sample credentials and demo exports are not production code. - Retain compatible form names and JS hooks where practical; document replacements where the design requires them. Existing jQuery/Vite/EJS integration and backend contracts need to be respected during the transfer. ### Initial production destination map | Prototype area | Existing production destination / integration point | | --- | --- | | Public navigation and page shell | views/partials/header.ejs, views/layouts/public.ejs, frontend/src/styles/public.css | | Plan choices / purchase | views/index.ejs, views/partials/plans.ejs, frontend/src/pages/home.js | | Private eSIM overview, installation and receipts | views/order.ejs, frontend/src/pages/order.js | | Top-up / renewal | views/topup.ejs, views/renew.ejs, corresponding frontend/src/pages modules | | Bulk orders and delivery | views/bulk.ejs, frontend/src/pages/bulk.js, order rendering | | Coverage and help | views/rates.ejs, views/faq.ejs, their page modules and relevant partials | | Shared controls and behaviours | frontend/src/components/ and frontend/src/utils/; extract shared CSS into frontend/src/styles/ | | New public management entry / new capabilities | Confirm route and endpoint availability; do not assume prototype hash routes already exist in the application | This is a starting map, not permission to edit these files now. Verify current selectors, legacy style imports and template boundaries before integration. ### Sign-off and transfer 1. Review the high-fidelity prototype across desktop, shorter laptop and phone sizes, including key recovery states. Preserve a dated approved snapshot and screenshots with the decision log, using locally saved artifacts until commits or sharing are explicitly authorised. Design sign-off alone is not push approval. 2. Once production integration is requested, port shared styles/assets/components first, then integrate one real page/flow at a time. Replace mock actions with existing handlers/API data; preserve the short checkout and correct eSIM context. 3. Validate the actual application against the signed-off prototype and V01–V12, including frontend checks/build and browser checks appropriate to each change. Record any agreed deviation; do not quietly lose accepted refinements. 4. Keep backend/provider-dependent features explicit. Design sign-off does not prove payment reconciliation, server-enforced TOTP, PWA private-link/cache behaviour or physical-device eSIM setup. Resolve their contracts and validation as those features are integrated, within the existing front-end-only scope. This approach reduces duplicate styling work and makes the transfer predictable. It does not imply a zero-change copy of the standalone prototype into the live app. ## Production implementation and review checklist When Yaya starts the real redesign: 1. Read this record, PROJECT-TODO.md and the latest handoff. Treat V01–V12 as required implementation/review criteria, not optional inspiration. 2. Implement using the existing frontend vanilla JS/CSS and EJS layout system. Likely touchpoints are frontend/src/styles/, shared frontend components, views/partials/header.ejs, public layout and relevant page templates. Verify exact ownership before editing; no backend work is authorised by this record. 3. Transfer behavior and design intent, not mock transaction/security logic. Use real plan availability, identifiers, prices and backend-confirmed states. 4. Verify actual production templates in Chromium, Firefox and WebKit at desktop, shorter laptop and phone sizes. Check matched gutters, sticky-tab placement, all four payment buttons, equal panel edges, expanded errors, keyboard focus, touchpad scrolling, zoom/reflow and natural stacked heights. 5. Compare the real routes with this decision list and current wireframe. Record evidence and outstanding dependencies before calling the redesign complete. If a real-data constraint conflicts with an accepted decision, surface the specific tradeoff rather than silently dropping the requirement. Production transfer status: **not started**. Prototype validation alone does not complete any production acceptance criterion. Keep commits and pushes subject to Yaya's existing explicit-approval rules. ## Homepage guide — 2026-09-27 How it works is the second homepage section, after purchase, rather than a separate page. Its anchor is #how-it-works; old #how prototype links open this section too. Put its navigation link immediately after Buy eSIM in the right-hand desktop navigation and phone menu, removing it from the left quick links. The guide fills the viewport available below the sticky header and anchor spacing, centering its content vertically, and grows naturally when stacked phone content needs more room. Preserve purchase selections when jumping between sections. ## Floating menu — 2026-09-27 Move prototype controls to the bottom left. A floating bottom-right menu icon on mobile layouts (the existing ≤1100px navigation breakpoint) opens a full-viewport modal navigation overlay, replacing the inline phone menu. Retain the desktop header links. The overlay makes background content inert, locks page scrolling, and keeps its own links scrollable on short screens. Escape or Close restores the previous page position and trigger focus; following a link closes the menu and unlocks the page before navigation. Keep How it works immediately after Buy eSIM. Prototype controls remain demo-only. Mobile header refinement: hide Top up balance, Renew number and Bulk orders at the mobile navigation breakpoint; retain all three in the overlay and in the desktop header. ## Mobile introduction and purchase folds — 2026-09-27 At the existing phone layout breakpoint (≤760px), give the introduction the first viewport and move Choose your plan into the next fold. Buy eSIM links to #buy-form and focuses the chooser below the sticky header, without resetting purchase input. How it works follows the chooser. Desktop keeps its existing copy and side-by-side introduction/purchase layout. Use minimum heights so short screens or enlarged text can scroll naturally; account for the measured header and prototype banner. Mobile copy condenses views/partials/hero.ejs without repeating its claims: “Private eSIM. Global connection.” / “Connect automatically in 160+ countries. No KYC.” / “Flat pay-as-you-go rates.” / “No data limits or speed throttling.” / “Funds and accounts never expire.” / “Pay with Bitcoin, Lightning, Monero, USDT or any crypto.” Coverage/rates and phone compatibility links remain. This is a copy adaptation of the existing source, not a new verification of service claims. ## Chooser spacing and anchor motion — 2026-09-27 Keep the mobile plan chooser at its natural content height with normal panel padding; remove its viewport minimum height and vertical centering, which caused large empty gaps inside the panel. The mobile introduction still fills the first fold. User-activated homepage section links scroll smoothly and focus their target; reduced-motion users get immediate scrolling. Direct loading and history navigation also stay immediate. Preserve sticky-header offsets and purchase input. Mobile purchase cleanup: remove the How it works / Already have an eSIM? helper row below the plan chooser. Both destinations remain in the mobile menu; desktop introduction links remain. ## Theme switch and clean design presentation — 2026-09-27 Add a 44px theme switch at the top right of the header on desktop and mobile. Use a shared monochrome palette across public/account pages, inputs, menus and dialogs. Start with the device colour scheme, honour an explicit stored choice before first paint, and keep switching functional when storage is unavailable. Yaya requested working with the design as if it were the actual site. Remove visible demo/prototype/sample disclaimers, review-only field fillers and the sample-account launcher; hide prototype controls. Use normal product wording in page titles, invoices, installation, support, security and home-screen dialogs. This supersedes the visible sample-fill UI in V10 and earlier review-control directions. Preserve meaningful service information (for example inbound-only SMS, unknown delivery status and unspecified usage currency) without inventing backend facts. Keep fixture IDs/private URLs stable internally. These are presentation changes to the local design. Payment, support, installation, authenticator and home-screen actions still use local mocks; this is not production integration. Existing endpoint/security/device validation boundaries still apply. ## Hero consistency and header controls — 2026-09-27 Use the mobile hero wording on desktop too, from a shared markup block: “Private eSIM. Global connection.” plus the coverage, No KYC, benefits and crypto-payment copy. Keep the desktop chooser beside it and the mobile Buy eSIM anchor. This supersedes the earlier instruction to retain desktop copy. The original vector logo now has a dark-theme lettering adaptation, both sized at 110px wide. Mobile menu and close controls are square to match other buttons. ## Desktop hero and navigation refinement — 2026-09-27 Removed the desktop-only “Pay. Install. Connect.” guide and its How it works / Manage links from the hero; the full How it works section remains below the chooser. Desktop main navigation now groups at the right beside the theme toggle (24px gap), with the maintenance links still beside the logo. Mobile retains its floating menu. This supersedes earlier notes retaining the desktop hero guide. Browser validation: 45 checks across Chromium, Firefox and WebKit desktop/phone; artifacts /tmp/silent-link-header-right, shared scenario header-right.mjs. Changes remain local and uncommitted. ## Homepage bottom-of-page layout — 2026-09-27 Remove the divider above How it works. Footer uses compact 14px padding; mobile reserves an 80px minimum height and right-side clearance for the floating menu. Measure footer height alongside header height. How it works fills the space between them at maximum scroll, with no trailing main padding to shift its center. Mobile guide cards use compact 14px padding/body text and 12px gaps; content still grows naturally on shorter screens. Align the guide anchor with the header edge. ## Next-section indicator — 2026-09-27 Show a small centered section-name/down-arrow anchor at the bottom of the first viewport: How it works on desktop, Choose your plan on phones where the chooser is the next fold. It uses existing smooth/reduced-motion navigation, scrolls away with the first section and clears the floating mobile menu. Homepage active navigation follows the visible section: How it works becomes active on anchor navigation and manual scrolling; returning to the purchase section restores Buy eSIM. Apply the same state in the mobile overlay. ## Homepage Help and live-chat support — 2026-09-27 Move Help into the homepage after How it works; place its nav link immediately after How it works in desktop and mobile menus. Section anchors scroll smoothly and active state follows the visible section. Preserve topic/contact deep links and contextual return to private installation. Both sections center vertically with viewport minimum heights; Help is now the last section and accounts for the measured footer. Expanded/phone content grows naturally. The original product has Matrix live chat plus email/Matrix links, not a contact form. Remove the prototype contact form. Its Help panel opens live chat instead. Use a redesigned launcher at bottom-right desktop and left of the mobile menu, with a matching panel, accessible close/Escape, scroll/focus restoration and an external-chat fallback. Embed the existing Matrix service only when requested; preserve its iframe/session across closes. The provider owns the inner chat UI. This live chat is the exception to otherwise local mock design interactions. ## Manual installation and Help indicator — 2026-09-27 Installation method order: iPhone, Android, Another device, Manual. Manual exposes SM-DP+ address, activation code and copy actions directly, replacing the old manual-details disclosure under other methods. Keep the method row touch/trackpad scrollable on narrow screens and retain focused/selected method visibility. Add Help with a down arrow at the bottom of How it works, matching the first-fold section indicator and existing smooth/reduced-motion navigation. Keep the guide content vertically centered with space above its indicator. PWA flow clarification: Add to Home Screen is currently on the private Overview page. I finished setup stays on Install and marks setup complete; it does not automatically advance to a PWA step. The home-screen action remains a design interaction rather than a working PWA installation.