# Signal Analyst wireframes

One Markdown wireframe for every page, state and email in the [page inventory](../page-inventory.html): **54 pages + 4 shells**. Each shows the layout the best-practice research calls for, not how the page looks today.

Every file follows [`_CONVENTIONS.md`](_CONVENTIONS.md):
- Job and primary action.
- Desktop (≤ 80 columns) and 390px mobile (≤ 38 columns) wireframes.
- Every state.
- Exact copy.
- "Why this layout", with references.
- "Changes from today", quoting the audit and slop findings.
- Open questions.

All wireframe blocks pass the width check, and every cross-link between files resolves.

Related: [navigation audit](../nav-audit.md) · [journey map](../journey-map.html) · [slop score by page](../journey-map.html#slop) · [page inventory](../page-inventory.html) · screenshots in [`../shots/`](../shots/).

## Navigation
All shells follow the navigation rules in [`_CONVENTIONS.md`](_CONVENTIONS.md#navigation-rules-from-nav-auditmd), which come from the [navigation audit](../nav-audit.md):
- A skip link, `<nav>` landmarks and `aria-current` on every page.
- Disclosure menus, never `role="menu"`.
- A logo-destination table per shell.
- Labelled `☰ Menu` on mobile.
- `↗` only for links that leave the site.
- 44px nav targets.
- The signed-in email shown next to Log out.
- A footer on every shell.

## The one structural change

The wireframes assume a new setup order:

**① Account → ② Connect Shopify → ③ Plan → ④ Start asking**, then **Account › Home**.

- Connecting Shopify before payment starts the backfill while the user is at checkout, which shortens time to first answer.
- **④ Start asking** ([C01](C01-start-asking.md)) is new. It's the step that gets the user to their first question in Claude, which today's flow never does.
- The old Status step becomes **Account › Home** ([P06](P06-account-home.md)): a setup checklist with a button on every unfinished item.
- Merchants installing from the Shopify App Store skip ① and ② ([E13](E13-shopify-app-store-install.md)).

If you keep "pay first", swap ② and ③; each affected file notes this.

## Shells
| Shell | Used by | File |
|---|---|---|
| Public | Home, pricing, legal, help, 404, Connect Claude | [_SHELL-public.md](_SHELL-public.md) |
| Setup | Sign up through Start asking; log-in and auth states without the step indicator | [_SHELL-setup.md](_SHELL-setup.md) |
| Account | Everything a customer returns to after setup, with shop switcher | [_SHELL-account.md](_SHELL-account.md) |
| Operator | `/operations/*`, with environment badge and shared tabs | [_SHELL-operator.md](_SHELL-operator.md) |

## Pages

### Public
| ID | Page | Status | Priority | Wireframe |
|---|---|---|---|---|
| P01 | Home | Audited · slop 9/10 | existing | [P01-home.md](P01-home.md) |
| C04 | Pricing | To create | P1 | [C04-pricing.md](C04-pricing.md) |
| C02 | Privacy policy | To create | **P0** | [C02-privacy-policy.md](C02-privacy-policy.md) |
| C03 | Terms of service | To create | **P0** | [C03-terms-of-service.md](C03-terms-of-service.md) |
| C15 | Help and support | To create | P1 | [C15-help-and-support.md](C15-help-and-support.md) |
| C14 | 404 and error page (all shells) | To create | P1 | [C14-404-and-error-page.md](C14-404-and-error-page.md) |
| P07 | Connect Claude (install instructions) | Audited · slop 3/10 | fixes P0 | [P07-connect-claude.md](P07-connect-claude.md) |

### Sign-in
| ID | Page | Status | Wireframe |
|---|---|---|---|
| P02 | Sign up (step ①) | Audited · slop 9/10 | [P02-account-sign-up.md](P02-account-sign-up.md) |
| P03 | Log in (incl. returning to Claude, Slack-only variant) | Audited · slop 9/10 | [P03-account-log-in.md](P03-account-log-in.md) |
| E01 | Magic link · request and sent | Exists | [E01-magic-link-request-and-sent.md](E01-magic-link-request-and-sent.md) |
| E02 | Magic link · landing | Exists | [E02-magic-link-landing.md](E02-magic-link-landing.md) |
| E03 | Forgot password · request | Exists | [E03-forgot-password-request.md](E03-forgot-password-request.md) |
| E04 | Reset password · set new | Exists | [E04-reset-password-set-new.md](E04-reset-password-set-new.md) |
| E05 | Google sign-in return | Exists | [E05-google-sign-in-return.md](E05-google-sign-in-return.md) |
| E23 | Email · sign-in link | Exists | [E23-email-sign-in-link.md](E23-email-sign-in-link.md) |
| E24 | Email · password reset | Exists | [E24-email-password-reset.md](E24-email-password-reset.md) |

### Setup wizard, connections and billing
| ID | Page | Status | Priority | Wireframe |
|---|---|---|---|---|
| P05 | ② Connect Shopify (+ optional sources) | Audited · slop 5/10 | P0 restructure | [P05-connect-shopify.md](P05-connect-shopify.md) |
| E09 | Shopify consent → confirm | Exists · handoff | P0 | [E09-shopify-consent-confirm.md](E09-shopify-consent-confirm.md) |
| E10 | Meta consent → choose ad account | Exists · handoff | P1 | [E10-meta-consent-confirm.md](E10-meta-consent-confirm.md) |
| E11 | Google Ads OAuth + account picker | Exists (typed IDs today) | P1 | [E11-google-ads-connect.md](E11-google-ads-connect.md) |
| E12 | Klaviyo connect and result | Exists | P1 | [E12-klaviyo-connect-result.md](E12-klaviyo-connect-result.md) |
| P04 | ③ Plan | Audited · slop 9/10 | P0 restructure | [P04-plan.md](P04-plan.md) |
| E06 | Stripe checkout handoff | Exists · handoff | P0 | [E06-stripe-checkout.md](E06-stripe-checkout.md) |
| E07 | Checkout return (paid · confirming · cancelled) | Exists | P0 | [E07-checkout-return.md](E07-checkout-return.md) |
| C01 | **④ Start asking** | To create | **P0** | [C01-start-asking.md](C01-start-asking.md) |
| E13 | Shopify App Store install entry | Exists (goes to old app home today) | P1 / P0 if listing | [E13-shopify-app-store-install.md](E13-shopify-app-store-install.md) |

### Claude and Slack
| ID | Page | Status | Priority | Wireframe |
|---|---|---|---|---|
| E14 | Claude shop picker | Exists | on P0 path | [E14-claude-shop-picker.md](E14-claude-shop-picker.md) |
| E15 | Claude unrecognized destination | Exists | — | [E15-claude-unrecognized-destination.md](E15-claude-unrecognized-destination.md) |
| C11 | Add to Slack (workspace install) | To create | P1 | [C11-add-to-slack.md](C11-add-to-slack.md) |
| C12 | Slack welcome DM and App Home | To create | P1 | [C12-slack-welcome-and-app-home.md](C12-slack-welcome-and-app-home.md) |
| E16 | Slack account linking · start (redirect) | Exists | — | [E16-slack-install-start.md](E16-slack-install-start.md) |
| E17 | Slack account linking · result | Exists | — | [E17-slack-install-result.md](E17-slack-install-result.md) |
| E18 | "This link can't be used" | Exists | — | [E18-slack-link-cant-be-used.md](E18-slack-link-cant-be-used.md) |
| E19 | Slack · choose shops for a channel | Exists | — | [E19-slack-configure-channel.md](E19-slack-configure-channel.md) |
| E20 | Slack · channel access saved | Exists | — | [E20-slack-channel-saved.md](E20-slack-channel-saved.md) |
| C13 | Shopify embedded app home | To create | P1 if listing | [C13-shopify-embedded-app-home.md](C13-shopify-embedded-app-home.md) |

### Account area
| ID | Page | Status | Priority | Wireframe |
|---|---|---|---|---|
| P06 | **Account › Home** (replaces Status) | Audited as Status · slop 8/10 | **P0** | [P06-account-home.md](P06-account-home.md) |
| C06 | Data sources | To create | P1 | [C06-manage-data-sources.md](C06-manage-data-sources.md) |
| C07 | Connected apps (Claude, Slack, bot reading setting) | To create | P1 | [C07-connected-apps.md](C07-connected-apps.md) |
| C05 | Plan & billing (usage, plan, invoices) | To create | P1 | [C05-usage-and-plan.md](C05-usage-and-plan.md) |
| E08 | Stripe billing portal handoff | Exists · handoff | P1 | [E08-stripe-billing-portal.md](E08-stripe-billing-portal.md) |
| C09 | Team and invitations (+ accept landing) | To create | P2 | [C09-team-and-invitations.md](C09-team-and-invitations.md) |
| E25 | Email · team invitation (orphaned) | Wire to C09 or delete | — | [E25-email-organization-invitation.md](E25-email-organization-invitation.md) |
| E26 | Email · thread invitation (orphaned) | **Recommend delete** | — | [E26-email-thread-invitation.md](E26-email-thread-invitation.md) |
| C08 | Settings | To create | P1 | [C08-account-settings.md](C08-account-settings.md) |
| C10 | Delete account and data | To create | P1 | [C10-delete-account-and-data.md](C10-delete-account-and-data.md) |

### Operator
| ID | Page | Status | Priority | Wireframe |
|---|---|---|---|---|
| C16 | Operations overview | To create (404 today) | P1 | [C16-operations-index.md](C16-operations-index.md) |
| P08 | Sources (incl. error state) | Audited · 500 | P1 | [P08-operations-sources.md](P08-operations-sources.md) |
| E21 | Source detail | Exists (blocked by 500) | P1 | [E21-operations-source-detail.md](E21-operations-source-detail.md) |
| P09 | Connections | Audited · slop 2/10 | P1 | [P09-operations-connections.md](P09-operations-connections.md) |
| P10 | Pipeline drafts | Audited · slop 5/10 | P1 | [P10-operations-pipelines.md](P10-operations-pipelines.md) |
| P11 | Slack thread replay | Audited · slop 4/10 | P2 | [P11-operations-slack-thread-replay.md](P11-operations-slack-thread-replay.md) |
| P12 | Source tests | Audited · slop 5/10 | P2 | [P12-operations-source-tests.md](P12-operations-source-tests.md) |
| E22 | Backfill session callback (no screen; error page only) | Exists | P2 | [E22-operations-backfill-session-callback.md](E22-operations-backfill-session-callback.md) |

## Found in code while wireframing
- **Shopify App Store installs never reach Signal Analyst.** `connectors/shopify.ts:74–86` sends installs with no pending-connection cookie to `SHOPIFY_LEGACY_APP_HOME_URL` (E13).
- **New users arriving from Claude can't sign up.** The Claude-return login hides the Sign up tab (`onboarding/flow.tsx:299`, P03).
- **The Google Ads account picker is half built.** The callback lists the accessible accounts (`google.ts:363`) but fails when there's more than one (`:254`) (E11).
- **The email sender falls back to `Signal <noreply@example.com>`** when `EMAIL_FROM` is unset (`lib/email.ts`), and subjects say "Signal", not "Signal Analyst" (E23–E25).
- **The Connect Claude page covers only Team/Enterprise.** Self-serve owners are more likely on Pro or Max (P07).
- **The backfill session start returns raw JSON on failure.** Its callback is served by the Pipelines console, not Signal Analyst (E22).

## Decisions needed (they change several wireframes)
1. **Setup order.** Connect Shopify before Plan (as drawn), or pay first?
2. **Billing for Shopify App Store installs.** Public Shopify App Store apps generally have to charge through Shopify's Billing API, which conflicts with Stripe checkout. This decides whether C13/E13 are launch scope and how P04 works for Shopify-installed merchants. Check current Shopify policy.
3. **Slack distribution.** A self-serve "Add to Slack" (C11) needs a publicly distributed Slack app, but PRD 0032 chose a private install. With a private install, the welcome DM (C12) goes to whoever installs it, possibly Signal staff.
4. **Who controls what the Slack bot reads.** C07 moves it to customers (Connected apps). P11 keeps an operator view. Pick one owner, or define operator as override only.
5. **Usage unit and allowance.** "Questions" or "credits", the `{allowance}` per plan, and what happens at the limit (P04, C04, C05, P06, E06, E08).
6. **Separate log-in routes.** `/login`, `/login?method=link`, `/login/forgot` split out of `/onboarding` (P03, E01, E03).
7. **Delete E26; wire or delete E25.** E25 is only needed if Team (C09) is built.

## Facts needed to fill placeholders
- **Placeholders:**
  - `{allowance_*}` per plan
  - `{support_email}` and `{from_address}`
  - `{legal_entity}` and `{postal_address}`
  - `{setup_minutes}` and a backfill time estimate
- **How to detect "Claude connected".** Proposed: the first `/token` exchange, exposed to the page (C01, P06).
- **Can one account connect several Shopify stores?** Affects E09 and the shop switcher.
- **Meta `ads_read` app review status** (E10).
- **Whether staging Stripe is in test mode** (E06).
- **Exact Claude menu labels** for Pro/Max vs Team/Enterprise (P07, C01).
- **Slack data:**
  - Channel names; only channel IDs are stored today (E19).
  - The bot's mention name.
  - Whether Claude connections can be listed and revoked per user (C07).
- **Data retention after disconnect or delete**, and whether C10 shares a job with Shopify `shop/redact`.
- **Legal review of C02 and C03.** They contain structure only, and need a decision on implied consent vs a checkbox at sign-up.

Each file's **Open questions** section has the page-specific detail (about 165 questions in total).