# KLIGO mobile app handoff

> Scope update (12 September 2026): `LAUNCH_SCOPE.md` takes precedence. Website first; native app later; all four categories. KLIGO bills subscriptions and paid placements only. Historical buyer-deal checkout, commission, escrow, booking-payment and payout proposals below are excluded from launch. See `MATERIALS_HANDOFF.md` for new/surplus material fields.


Status: responsive web reference implemented; native iOS/Android application not yet built. This guide and the website source are the starting point for the full application, not an installable store release. The Developer Kit at `/design-system#mobile` links to the real screens. Do not build a separate throwaway mock app.

## Deliverable boundaries

| Deliverable | Current state | Next implementation |
| --- | --- | --- |
| Laptop and mobile website | Shared responsive web code, working demo flows | Production services and device QA |
| iOS and Android app | Visual and interaction reference in the website | Native screens, device integrations and signed builds |
| Shared backend | Browser-local demo stores | Durable authenticated APIs used by web and native clients |
| Developer download | Original source folders, assets, tests, lockfile and guides | Add the actual app source and setup instructions when implemented |

The complete website package has the runnable reference. The smaller Developer Kit is a component and asset reference, not an independently runnable application. Follow `DEVELOPER_HANDOFF.md` for local setup and domain integration contracts.

## Reuse and adaptation

| Source | App usage |
| --- | --- |
| `public/brand/logos/full-primary.svg` | Preserve the official logo without redrawing it |
| `app/globals.css`, generated `public/brand/kligo-tokens.css` | Translate colors, typography, spacing, molded elevation and radii to native tokens |
| `components/kligo/button.tsx`, `tabs.tsx`, `choice-card.tsx` | Implement native equivalents with the same states and dimensions |
| `components/kligo/mobile-app-navigation.tsx` | Reference for tab order, role destinations and active states |
| `components/kligo/mobile-profile-controls.tsx` | Profile section and account shortcut behavior |
| `components/marketplace/listing-card.tsx`, `listing-gallery.tsx` | Shared visual contract for compact cards, swiping and sponsored treatment |
| `components/marketplace/discovery-search.tsx` | Consistent What / Where / When / Options interaction |
| `components/i18n/` | Reuse approved labels and RTL requirements; adapt the browser context |
| Existing browser stores and sample catalogs | Demo fixtures and behavior references; replace with authenticated server data |

React DOM, CSS, local/session storage, map rendering and browser uploads cannot simply be copied into native screens. Extract pure domain types and validation where possible. Keep platform views separate and use one authoritative API for identity, inventory, prices, payments and messages. The native framework choice belongs to the full app implementation; no unused scaffold or dependency has been added here.

## Navigation and screen map

Bottom tabs: Home, Saved, Create, Messages, Profile. Create opens listing creation. Provider accounts use provider Messages and company Profile. Authentication has no product tab bar. Secondary screens return to their parent without discarding form drafts. Deep links must check authentication and ownership on the server.

| Flow | Existing web reference | App behavior |
| --- | --- | --- |
| Home and discovery | `/`, `/equipment`, `/services`, `/parts`, `/materials` | Compact categories, consistent search, eight results per mobile page |
| Map and filters | Map and Filters controls on discovery screens | Direct map view, coordinated results, bottom-sheet filters and explicit apply |
| Listing and company | Open an actual catalog card; `/companies` | Photo gallery, essential offer/provider details and clear contact action |
| Saved | `/customer/saved` | Grid/list switch and account-synced saved equipment/providers |
| Registration | `/create-account`, `/sign-in` | Personal/company entry and secure session recovery |
| Customer work | `/customer/requests/new`, `/customer/quotes`, `/customer/bookings` | Request, compare, accept and booking states |
| Messaging | `/customer/messages`, `/provider/messages` | Authorized threads, unread state and deep-linked notifications |
| Listing creation | `/provider/listings/new`, `/provider/listings` | Draft, photos, details, review, publish and manage |
| Account | `/customer/account/profile`, `/provider/profile` | Short sections, persistent drafts and field-level correction |
| Preferences and help | `/customer/account`, `/customer/account/preferences`, `/customer/account/support` | Simple preferences, settings and support access |
| Advertising | `/provider/campaigns`, `/provider/campaigns/new` | Explain each placement and price before selection; simple campaign status |
| Plans, billing and badges | `/provider/plans`, `/provider/billing` | Clear subscription, invoice and badge eligibility flows |
| Reviews and reports | Company detail and report actions after contact | Server-enforced eligibility and moderation |

## Product rules to preserve

- Bright white surfaces, yellow #FBB104 and black #0A0A09. Use the approved molded controls and subtle card shadows.
- Keep the logo visible during loading; only the yellow top/bottom bars fill. Support reduced motion and a recoverable loading timeout.
- Keep fixed tabs clear of phone safe areas, the keyboard, sheets and primary actions. Minimum comfortable touch targets are 44 points; support larger text and screen readers.
- Two-column compact discovery on normal phone widths, one column below 360px. Keep detail content on detail screens and use explicit pagination instead of endless feeds.
- Listing photos and titles always open the relevant detail. Touch actions work immediately; never require hover. Retain real photo swiping and clear sponsored labeling.
- At most one sponsored card per eight result listings; hero placements are separate slots. Paid visibility never grants trust approval.
- Preserve search inputs when opening results, filters or a listing. Apply min/max price and contextual options consistently.
- Show loading, empty, offline, permission-denied and retry states. Never turn an error into a misleading empty result. Prevent duplicate submissions and surface unsaved changes.

## Full app implementation sequence

1. Agree the API contracts and authentication model. Define stable listing/company/user IDs, permissions, pagination, price units and time zones. Convert demo data to isolated fixtures.
2. Build the real app shell, native brand primitives, navigation, deep links, localization and account session handling. Connect one complete discovery-to-detail-to-save journey to the backend first.
3. Add requests, quotes, bookings, messages, profiles and listing creation with durable drafts and authorized uploads. Then integrate advertising, plans, invoices, reviews and support.
4. Add device integrations where needed: camera/photo selection, location with manual fallback, secure session storage and push notifications. Request permissions only at the relevant action.
5. Verify complete customer/provider journeys on physical iOS and Android devices, including small screens, large text, RTL, keyboard, slow/offline networks and interrupted uploads. Check current store requirements when preparing release; billing and privacy choices must be reviewed for the actual product and region.
6. Deliver native source folders, dependency lockfiles, sanitized configuration example, local run/build instructions, API documentation, test fixtures, release instructions and an honest completion checklist. Keep signing credentials and production secrets outside downloads.

## Validation and known limits

Web type checks, builds and automated route/workflow tests provide code-level coverage. Browser visual review of the recent mobile batches was blocked by the environment's URL policy, so device appearance and interaction still need human review. No native device tests or store submissions have occurred. Payments, chat delivery, badge approval, identity and analytics are currently demonstration workflows; do not present them as production integrations. See `DEVELOPER_HANDOFF.md` for the full replacement matrix.

## Appearance

The responsive web source now includes complete light and dark appearances, a remembered browser preference and translated controls. Reuse the palettes and rules in `DARK_MODE_HANDOFF.md` for the later native app; native appearance persistence and platform behavior require implementation there.