shopflow-suite

Shopflow Product Surface Spec

Purpose

This document defines the responsibilities and boundaries of Shopflow’s four UI surfaces:

It also locks the information architecture for the Shopflow home surface.

In plain language:

this is the floor plan for the front desk.

Surface Hierarchy

Shopflow has one primary surface and three supporting surfaces.

Surface Role Priority
Side Panel primary application surface Primary
Popup quick router and summary surface Secondary
Content UI thin inline page augmentation Secondary
Options settings and policy surface Secondary

Current Repo Materialization Note

Current repo-owned alpha truth in this lane:

Not yet repo-verified as materialized product surfaces in this lane:

Therefore:

treat Content UI and Options as locked responsibilities first, not as already-shipped Shopflow surfaces.

Product Language and Locale Rules

Public-facing Shopflow surfaces must stay:

Product UI must stay:

Current repo truth may claim:

Current repo truth must not claim:

Hard rule:

New user-visible strings must route through shared locale catalogs. Scattered bilingual literals are product-surface drift.

Product Surface Rules

  1. Main product lives in Side Panel
  2. Popup is not a second main app
  3. Content UI stays thin
  4. Options owns settings and policy explanation, not operational work
  5. All surfaces must consume capability truth from runtime/view-model, not raw DOM guessing

1. Side Panel

Purpose

The Side Panel is the main Shopflow app surface.

It exists to:

Side Panel Must Do

Side Panel Must Not Do

Core Sections on the Home Surface

The Shopflow home surface must always be organized into these seven sections:

  1. Top Brand Bar
  2. Readiness Summary
  3. Current Site Summary
  4. Capability Grid
  5. Quick Actions
  6. Recent Activity
  7. Secondary Navigation

2. Popup

Purpose

Popup is a lightweight launcher and status router.

Popup Content Budget

Allowed:

Forbidden:

3. Content UI

Purpose

Content UI exists to add thin, contextual assistance inside the merchant page.

Content UI Must Do

Content UI Must Not Do

Isolation Rule

If Content UI mounts substantial React UI, it must use Shadow DOM isolation.

Why:

4. Options

Purpose

Options is the settings and policy explanation surface.

Options Must Do

Options Must Not Do

Home Surface Information Architecture

A. Top Brand Bar

Purpose:

Contents:

B. Current Site Summary

Purpose:

Contents:

B.1. Readiness Summary

Purpose:

Contents:

C. Capability Grid

Purpose:

Canonical capability cards:

Rules:

D. Quick Actions

Purpose:

Rules:

Examples:

E. Recent Activity

Purpose:

Rules:

E.1 Evidence Routing

When an evidence item still needs capture, review, or recapture and the current or latest source page is already known, the surface may expose a direct route back to that source page.

Why:

F. Secondary Navigation

Purpose:

Rules:

Suite Internal Alpha Surface

Shopflow Suite is an internal control-plane lobby.

It must:

It must not:

Purpose:

Canonical destinations:

Home Surface States

The home surface must support at least these six states:

State Meaning Required UX Behavior
loading app is detecting site/page/capabilities skeleton + loading text
supported_ready supported page with runnable capabilities capability cards active, primary CTA visible
supported_partial store supported but only some capabilities available partial cards active, unavailable reasons shown
unsupported_site site not supported honest unsupported state, route to help/settings
permission_needed support exists but host/browser permission is missing permission card plus grant action
error runtime or adapter failure error summary plus retry or logs route

UI Layering Rule

Shopflow UI must follow this layering model:

Rules:

  1. primitives must not depend on features
  2. patterns must not depend on pages
  3. features may depend on patterns + primitives
  4. pages compose other layers but should not re-implement primitive styling
  5. deep UI layers must consume props or schema-safe view-models, not raw browser data

Canonical Home View Model

The home page must not consume ad-hoc raw runtime blobs.

It should consume a shaped view-model such as:

type SidePanelHomeViewModel = {
  appTitle: string;
  appStatus: 'live' | 'idle' | 'unsupported' | 'error';
  site: {
    siteId: string;
    siteName: string;
    host: string;
    pageKind: 'product' | 'search' | 'deal' | 'cart' | 'manage' | 'unknown';
    urlLabel: string;
  };
  capabilities: Array<{
    id:
      | 'extract_product'
      | 'extract_search'
      | 'extract_deals'
      | 'run_action'
      | 'export_data';
    label: string;
    description: string;
    status:
      | 'ready'
      | 'unsupported_page'
      | 'permission_needed'
      | 'not_implemented'
      | 'degraded'
      | 'blocked';
    reason?: string;
  }>;
  quickActions: Array<{
    id: string;
    label: string;
    variant: 'primary' | 'secondary' | 'ghost';
    disabled?: boolean;
  }>;
  recentActivities: Array<{
    id: string;
    label: string;
    timestampLabel: string;
    href?: string;
  }>;
};

Design Direction

Shopflow should feel like:

It should not feel like:

Short version:

Shopflow should feel like a shopping copilot, not like a noisy admin console.

Surface Ownership Summary

Surface Owns Must Not Own
Side Panel capability rendering, primary action launch, recent activity, navigation raw DOM probing, duplicate settings systems
Popup route-in, quick summary, one primary CTA heavy operational workflows
Content UI inline CTA, highlight, badge, lightweight affordance main app shell, full settings, large dashboards
Options settings, permissions, policy explanation main operational workflows
This site is open source. Improve this page.