# Intended end-state — UX flow, screens & features

The destination for the site-ng (Flask) rebuild, as a visual/UX reference.
This is *where the interface is going* — not what's built today. Treat it
as the fixed picture we iterate toward; feature order is flexible (the
phasing in `build-feature-design.md` / `browse-design.md` is one possible
order, not a contract).

Companion docs: `build-feature-design.md` (kit-builder mechanics + schema),
`browse-design.md` (filter/search/sort/paginate/view). Memory:
`feature-site-share-builds`, `site-core-purpose-restock-latency`,
`feature-site-interactive-ar-silhouette-nav`, `site-migration-perl-to-flask`.

---

## Positioning — clarity at a glance ("we don't sell parts")

**The risk:** moving the intro prose off the home page (to make room for the
silhouette nav) could leave a first-time visitor thinking we're just
another retailer. We are **not a store** — we're a **price & availability
comparison/search engine** that tracks in-stock AR-15/AR-10 parts across
many retailers and links shoppers straight to them. That has to read **at a
glance**, above the fold, even with the prose moved to About.

**Three always-visible devices carry the message:**

1. **A persistent micro-tagline under the wordmark** (every page), e.g.
   *"In-stock AR-15 & AR-10 parts across every retailer — we find them, you buy direct."*
2. **A hero headline + one-line subhead** on the home page (candidates below).
3. **A tiny "How it works" strip** (3 icons: *We track N retailers → You
   compare in-stock parts → Buy direct from the seller*). One glance = the
   whole model, including that checkout happens on the retailer's site.

**Tagline candidates** (headline / subhead — pick one, refine later):

- **A.** "Find In-Stock AR-15 & AR-10 Parts — Fast." /
  *"A live availability search across N retailers. We don't sell parts — we show you who has them in stock and link you straight there."*
- **B.** "Every AR Part. Every Retailer. In Stock Right Now." /
  *"The in-stock search engine for AR builders — not a store. Compare availability and price, then buy direct from the retailer."*
- **C.** "Who's Got It In Stock?" /
  *"We track AR-15 & AR-10 parts across N retailers in real time so you don't have to. Comparison engine, not a store."*

*Recommendation: B* — leads with the aggregation breadth + the in-stock
hook (our core value), and the subhead kills the "are you a store?"
ambiguity in one sentence. The "N retailers" count is live data we already
have (the company list), so it stays honest and current.

---

## The journey

```
 LAND ─▶ DISCOVER ─▶ ADD ─▶ REVIEW BUILD ─▶ SHARE ─▶ (others view/fork/vote)
                                  │                         │
                                  └────────▶ ALERT ◀────────┘
                                     "tell me when my missing parts restock"
```

Every screen below is a stop on this one journey. Discovery doubles as the
site's standalone purpose (the in-stock tracker); the rest is the
kit-builder beachhead built on the same foundation.

---

## 1. Land — home

```
┌─────────────────────────────────────────────────────┐
│  AR PARTS FINDER                                       │
│  In-stock AR-15/AR-10 parts across every retailer —    │  ← micro-tagline
│  we find them, you buy direct.                         │
│                                   In-Stock-o-Meter ▓▓▓░ 73%│
│                                                       │
│            [ interactive AR silhouette ]              │
│      hover a part → lights up + labels → click →      │
│      that category's in-stock results                 │
│                                                       │
│  How it works:  ① We track N retailers                │
│                 ② You compare what's in stock         │
│                 ③ Buy direct from the seller          │
│                                                       │
│  or pick a category:  Barrels(120) BCGs(88) Lowers… │
│  [ Start a Build ]      [ Popular Builds ]            │
└─────────────────────────────────────────────────────┘
```
**Features:** silhouette nav (marquee) + category chips (always-works
fallback) + live stockometer + the positioning devices above + two entry
CTAs (build / popular builds). Intro prose lives on About.

---

## 2. Discover — category / browse results

*(This is today's browse page, fleshed out — see `browse-design.md`.)*

```
┌──────────────┬──────────────────────────────────────┐
│ Categories   │  search [_______]  $[min]-[max]  sort▾│
│  Lower ▸     │                         [▦ card][≣ tbl]│
│  Upper ▸     │  ┌────┐ ┌────┐ ┌────┐ ┌────┐           │
│   Barrels 120│  │img │ │img │ │img │ │img │           │
│   BCGs 88    │  │name│ │name│ │ …  │ │ …  │           │
│  Other ▸     │  │$199│ │$249│ │    │ │    │           │
│              │  │view│ │view│ │    │ │    │           │
│ Stockmeter   │  │+Add│ │+Add│ │+Add│ │+Add│           │
│  ▓▓▓░ 73%    │  └────┘ └────┘ └────┘ └────┘           │
│              │           ‹ 1 2 3 4 ›   48/page        │
└──────────────┴──────────────────────────────────────┘
```
**Features:** category sidebar w/ live counts; text search (wildcard);
price-range filter; retailer filter; sort (newest / price / name);
pagination; card↔table toggle. Each result: image, name, retailer, price,
in-stock badge, **"view →"** (affiliate via `jump.cgi`), **"+ Add"** to
build. Serves both the standalone tracker and the kit-builder picker.

---

## 3. Add + Review — the build

```
 Header (every page):  [ 🔧 Build: 5 parts · $1,240 ▾ ]

┌─────────────────────────────────────────────┐
│  Your Build                      total $1,240│
│  ─ Lower ──────────────────────────────────  │
│   ✓ Aero Stripped Lower   $89   [in stock] ✕ │
│   ✓ Geissele Trigger     $240   [in stock] ✕ │
│  ─ Upper ──────────────────────────────────  │
│   ✓ Faxon 16" Barrel     $260   [OOS now]  ✕ │
│   ◯ (no BCG yet)                              │
│   ◯ (no handguard yet)                        │
│                                               │
│  [ Share this build ] [ Notify me on restock ]│
└─────────────────────────────────────────────┘
```
**Features:** persistent header build-chip (count + running total);
grouped-by-type kit layout; **live per-item in-stock status**; remove
buttons; optional empty "slots" hinting what a complete rifle still needs;
share + restock-alert CTAs. (Working build held in session until shared.)

---

## 4. Share — public build page (viral / SEO / revenue surface)

```
┌─────────────────────────────────────────────┐
│  "My budget 16" carbine"      ▲ 42 upvotes    │
│  Shared · arpartsfinder.com/b/k3Xq9p          │
│  Total: $1,240   ·   4 of 5 parts in stock    │
│                                               │
│   Aero Lower    $89  [in stock]  [ Buy → ]    │
│   Faxon Barrel $260  [OOS]       [notify]     │
│   …                                           │
│                                               │
│  [ ▲ Upvote ]  [ Fork this build ]            │
│  [ ✉ Email me when the OOS parts come back ]  │
└─────────────────────────────────────────────┘
```
**Features:** crawlable public page (short URL); upvote; fork-into-your-own;
per-item buy buttons via `jump.cgi` (affiliate); restock-alert subscribe.
The buy buttons reinforce positioning — you leave to buy at the retailer.

---

## 5. Alert + loop — the differentiator

The site already detects restocks in **minutes** (its whole reason for
being — see memory `site-core-purpose-restock-latency`). The build feature
weaponizes that: watch a **whole kit**, not one part. A missing piece
restocks → email → click through → commission. A **Popular Builds** gallery
(sorted by votes) is the inspiration/SEO surface that feeds people back to
the top of the journey.

---

## Cross-cutting features

- **Affiliate-safe links everywhere** — all "buy/view" go through the
  production `jump.cgi?site=<parts.id>` (commission + click logging).
- **Human type labels** (the short nav forms) everywhere parts appear.
- **Server-rendered + htmx** — every meaningful state has a real,
  crawlable URL (SEO is the commission channel); htmx just avoids reloads.
- **Anonymous** — no accounts; a secret edit-token cookie lets a creator
  re-edit a shared build.

---

## How to use this doc

This is the shared picture of the destination. To stay efficient: pick any
slice of the journey to make real next; the load-bearing foundations that
unlock the most downstream are the `search_parts()` query refactor (powers
discovery + the picker) and the `build`/`build_item` tables (everything
from "review" on). Build order is otherwise yours to drive.
```
