REDESIGN_QUESTIONS.md

Redesign decisions and data gaps

Header logo

• This checkout has no /redesign header counterpart. The current light-only storefront uses the admin's Site Header Logo on every header. A header with light text gives that logo a light backing; checkout and payment use a light header surface. The admin's dark-mode and custom header logo fields are reserved for a future dark presentation.

Profile phone country

• The October 9 screen recording shows an Indian delivery phone number, then +1 beside that same number as soon as the profile form appears. The form previously used iso_2 from GET /user/profile and fell back to US; the shared phone input also defaulted to US and skipped location detection when it received a saved number. A local mock with a saved number and blank iso_2 reproduced +1. Selecting India, entering a synthetic number, and saving it in the mock kept IN through the mock checkout step. The recording does not show whether the API returned an empty iso_2 or stored US, so inspect that field for the affected account before changing its data. A delivery address does not currently set the account phone country. The mock also exposed a separate bug: PhoneInput.handleCountryChange cleared the displayed number but sent the previous number to onPhoneChange, temporarily leaving parent form state out of sync.
• Clearout's System Settings page shows Default country = India, and the public storefront receives defaultISO2: "IN". Phone fields now use that setting when the customer has no saved phone country. A saved iso_2 still takes precedence; phone verification remains a separate OTP step. The affected account's profile response has not been inspected.

Checkout address selection

• This checkout has no local /redesign counterpart. The address API has no last-used or default marker. Checkout remembers the customer's last selected address ID in a browser cookie, validates it against the current address list, and selects the sole saved address automatically. With multiple addresses and no prior choice on that browser, the customer selects one. The checkout recalculates the cart and market after restoring a choice.

Blogs

• This checkout has no /redesign blog counterpart. The live slate theme and the supplied blog reference define the listing, article, and home highlights: editorial hero, topic filters, search, paginated cards, article content, linked products, and related stories.
• The supplied listing reference uses a plain "Blogs" heading with a short subtitle, no eyebrow, and rounded topic filters and search. The intro flows into the filters without a divider; the filter divider alone separates controls from content. Articles marked editor_pick appear in a top carousel. Blog cards use the shared hairline border and soft shadow. Card hover changes only the shadow, while featured articles have a high-contrast action and smaller cards use quiet outlined actions. The listing omits the story count.
• The public GET /blogs total controls all blog entry points. The dev panel now has published blogs; categories alone do not enable the links when the total is zero.
• GET /blog-categories is wrapped as data.data on the dev panel, and the service supports both that and an array response. The dev GET /blogs/{slug} response wraps the article in data.blog; SEO fields are under blog.metadata, and the product array is blog.products with market-formatted prices on each variant. The service normalizes these fields for the page.
• The list response has no reading-time field or article content. The storefront enriches visible list items and editor picks with article details before rendering their reading times; cards outside those lists fetch details through SWR with retries. A backend reading_time_minutes field would avoid these extra requests. The current detail response has no related-articles array, so that section appears only when the API supplies it.
• The public blog list and detail responses do not expose a view count; this was confirmed against both live endpoints on 2026-10-15. The documented BlogApi has no view-tracking endpoint. An accurate public count needs the panel to define how article opens are deduplicated, store the count, and return it in the blog resource; the storefront should not invent a client-side number.
• Article sharing uses the configured public storefront origin and offers native sharing on supported mobile browsers or a platform picker; no automatic copy action is used. The dev sample titled "12 Genius Ways" currently contains only one numbered idea and links a 6-drawer chest. Those are admin content associations and need correction in the panel for the published article to match its title and topic.

Storefront font setting

• The web admin offers a Google Font Family field. The storefront reads web.googleFontFamily from the existing GET /settings response and applies it to body and display typography; an empty or invalid value retains the current bundled fonts.
• The linked API documentation redirects to the admin login in this environment, the direct GET /api/settings/web request is blocked, and the sibling panel repository is unavailable in this checkout. Confirm the exact field name and a populated response against the panel before relying on a production font selection.

Customer app links

• This checkout has no /redesign counterpart for the open-app sheet. The existing storefront sheet and theme tokens remain the visual reference.
• The web can open an installed customer app only when the app registers the configured customerAppScheme (or legacy appScheme); Android also uses the package ID from the configured Google Play URL. iOS accepts an Apple App Store or TestFlight fallback, and Android accepts a Google Play fallback. Confirm the native app's registered scheme and package against these settings on physical devices.
• The dev admin's customer app and web Play Store links now both use the user-confirmed HyperCommerce package com.hyperCommerce.customer. The configured scheme remains customer-hypercommerce. The iOS TestFlight link remains the existing dev invite at the user's request; iOS app launching has not been verified on a physical device.
• Admin App Settings supplies the customer scheme and customer store URLs, and Web Settings supplies the app download store URLs. It does not specify accepted deep-link hosts or routes, so the native app must confirm support for the storefront's products destination or expose a route contract. The app prompt waits until the customer accepts or declines analytics cookies, preventing the two overlays from appearing together.
• An Android user retested the direct intent link in Chrome after deployment: the Play Store fallback still opens, and that listing shows Open, confirming com.hyperCommerce.customer is installed. The installed build therefore does not resolve the website's customer-hypercommerce://home intent in Chrome. The mobile app team needs to inspect its exported ACTION_VIEW filter with DEFAULT and BROWSABLE, the registered scheme/host, and its routing for customer-hypercommerce://products?slug=...; then publish an updated app or provide the actual registered scheme so the admin setting can match it.
• The Android home prompt now tries customer-hypercommerce://products at the user's request; iOS keeps its existing home target. This still requires a matching handler in the installed app; a package ID alone cannot establish one.

Shared cart links

• This checkout has no /redesign counterpart for sharing a cart. The existing cart page and /design-system primitives define the Share action and recipient sheet.
• The API documentation confirms POST /user/cart/share, GET /user/cart/shared-lists/{token}, and POST /user/cart/shared-lists/{token}/import, all authenticated and without request bodies. Its success schemas document only data: null, so the exact token, preview item, and import result payloads remain unverified. The storefront validates the token and every preview item before displaying or sharing them; the live response should be checked against the panel resource when it becomes available.
• Shared links use /cart/shared-lists/{token}/, matching the backend-generated customer link shape. Signed-out recipients see a sign-in action before the authenticated preview request.
• Vercel and Apache hosts rewrite the token path to the static shared-cart page while keeping the original URL in the browser. Static export cannot prebuild a page for arbitrary tokens, so the view reads the token from the visible pathname.
• The header cart drawer is the guest/offline cart. Its share action opens sign-in and sends the customer to /cart/ after authentication. Only the authenticated cart creates links through POST /user/cart/share.
• The documented share and import endpoints accept no item selection, so links contain the whole server cart and importing adds the whole shared list. The creator sheet shows a short link label and copies the full URL on request. The link uses the current customer site origin.

Order details

• The referenced src/redesign/, THEME_REDESIGN.md and GAP_ANALYSIS.md are absent from this checkout. The existing storefront components and slate theme are the visual baseline for the approved combined product/timeline/return/refund card.
• Customer order responses add an optional refunds collection without changing existing fields. Item displays use refund allocations, not the order-wide refund amount or original payment method. Settled obligations retain their allocated quantity/amount and resolve their payment status and destination through settled_by_refund_id.

Seller registration

• Country-based onboarding uses five focused steps: Account, Business address, Bank details, Documents, and Review. Empty dynamic sections are skipped. Existing storefront tokens and shared UI primitives define this form; the API owns field labels, order, types, choices, defaults, and required flags. Country changes reset dynamic answers and uploads; country lookup failures offer Retry before proceeding.

• There is no src/redesign/ counterpart for the seller registration landing page. The existing storefront layout and design tokens therefore remain authoritative while section titles, subtitles, labels, item copy, and media are populated from the seller landing API. Benefit images are optional and fall back to the existing static icons when no uploaded image is configured.

Customer support

• There is no /redesign counterpart for the customer support timeline. The live storefront tokens and the approved single-timeline support flow therefore define this screen until a dedicated redesign reference is added.

Watch & Buy

• The current checkout has no src/redesign/ counterpart for Watch & Buy. The live customer API and existing storefront tokens therefore define the first implementation.

• /watch-and-buy combines a vertically stacked heading and Stories rail with a regular Explore grid of 9:16 reel tiles. Each tile uses the API preview source and shows duration, caption, profile, and supported like count. Selecting a tile opens a centered, full-height, vertically snapping viewer at that item; media fills the player, audio preference persists while scrolling, double-tap likes, and close returns to Explore. Selecting the profile inside a reel keeps the viewer open and narrows it to that seller's reels, matching the customer app; stories remain accessible from the Stories rail.

• Reel- and story-linked products appear in the same persistent horizontal rail and continue to the existing PDP. Direct add-to-cart is intentionally deferred because the Watch & Buy response does not include minimum quantity, step size, addon requirements, or full stock rules.

• The approved viewer hierarchy uses a top back action and sound toggle, right-side like/share actions, seller identity plus caption above a compact bottom product rail, and a PDP action in place of direct add-to-cart until the API exposes full cart rules.

• Reel sharing uses the configured public storefront origin plus the reel slug as the durable deep link, preventing localhost links from reaching external recipients. Mobile-width browsers with Web Share support open the device share sheet directly for installed apps such as Instagram, TikTok, and Snapchat; the URL is embedded in the outgoing message, reel artwork is attached when the browser supports file sharing, and slug pages publish reel-specific Open Graph/Twitter imagery for rich link previews. Share artwork resolves in order from reel cover, image preview, seller profile, then linked-product image so every available fallback remains attractive. Desktop and unsupported devices get a larger reel-preview sheet with creator, caption, product count, WhatsApp, Telegram, Facebook, X, Threads, Pinterest, Reddit, LinkedIn, email, and copy-link options. Every desktop option uses the platform's standard web share or compose URL instead of a native-app handoff; below the 1024px header cutover, the existing native share flow remains primary. Copying falls back to selection-based browser copying when the modern Clipboard API is unavailable, and a failed native share degrades to the platform sheet or a copied link instead of a dead end.

• Double-clicking or double-tapping a reel likes it with a heart burst at the interaction point. On desktop, vertical wheel gestures over the surrounding black viewer area navigate the centered reel feed while the document stays locked.

• Explore reel tiles stay visually stable under hover and use the compact play-duration badge plus pointer cursor to communicate that the whole tile opens the reel without obscuring its artwork.

• Story progress starts after media readiness, uses the API duration_ms value when supplied (with a five-second fallback), follows real video playback, and pauses while the customer holds the story or browses its product rail.

• Comments, follows, saves, view counts, and product-filtered reels are not rendered because the customer API does not expose those contracts. The reference's view-count position uses the supported like count and heart icon rather than mislabelling likes as views.

• Videos expose captions as visible post text, but the API does not return timed caption tracks. The player includes an empty WebVTT fallback until the contract supplies caption URLs.

• Seller onboarding progress uses a compact step count and segmented bar below 1024px, with equal-width labelled steps above that breakpoint. Uploads use a single card with a real image thumbnail, filename, size, and explicit Replace/Remove actions; native file controls remain hidden.