descrybe/docs/design-gaps.md

# Descrybe v2 — UI / UX design gaps vs legacy

**Audit date:** 2026-08-03  
**Legacy:** `f:/laragon/www/_MY/descrybe`  
**v2 web:** `f:/laragon/www/_MY/descrybe-v2/apps/web`  
**Scope:** Visual and UX parity only (routes, nav, dialogs, stubs, layout). No fixes in this pass.  
**Related:** [status-and-gaps.md](status-and-gaps.md) (backend/product gaps), [features.md](features.md)

Priority legend:

| Priority | Meaning |
|----------|---------|
| **P0** | Blocks daily-ops parity or presents a broken/misleading UI for a core path |
| **P1** | Important feature parity / polish; workaround exists or path is secondary |
| **P2** | Nice-to-have chrome, marketing, or low-traffic screens |

---

## 1. Legacy dashboard + auth routes

### Auth / entry (`app/(auth)` + related)

| Route | File |
|-------|------|
| `/login` | `app/(auth)/login/[[...login]]/page.tsx` |
| `/signup` | `app/(auth)/signup/[[...signup]]/page.tsx` |
| `/accept-invitation` | `app/accept-invitation/page.tsx` |
| `/onboarding` | `app/onboarding/page.tsx` |

Auth layout: `app/(auth)/layout.tsx` (Clerk SignIn/SignUp, branded header with **Book a Demo**, privacy/terms footer).

### Dashboard (`app/dashboard`)

| Route | File / notes |
|-------|----------------|
| `/dashboard` | `page.tsx` → news + stats home |
| `/dashboard/products` | `products/page.tsx` |
| `/dashboard/feeds` | `feeds/page.tsx` |
| `/dashboard/feeds/[feedId]/mapping` | `feeds/[feedId]/mapping/page.tsx` (older mapping) |
| `/dashboard/feeds/[feedId]/mapping-v2` | `feeds/[feedId]/mapping-v2/page.tsx` (**current** entry from feed actions) |
| `/dashboard/export-feeds` | `export-feeds/page.tsx` |
| `/dashboard/export-feeds/new` | `export-feeds/new/page.tsx` (`?format=xml\|csv` → full `ExportFeedBuilder`) |
| `/dashboard/export-feeds/[feedId]` | exists as edit path used by table “Edit” |
| `/dashboard/categories` | `categories/page.tsx` |
| `/dashboard/categories/[categoryId]/title-formula` | formula builder |
| `/dashboard/categories/[categoryId]/description-formula` | description formula builder |
| `/dashboard/attributes` | `attributes/page.tsx` |
| `/dashboard/standard-fields` | `standard-fields/page.tsx` |
| `/dashboard/tasks` | `tasks/page.tsx` (background tasks) |
| `/dashboard/billing` | `billing/page.tsx` |
| `/dashboard/settings` | `settings/page.tsx` |
| `/dashboard/plans` | `plans/page.tsx` |
| `/dashboard/process/new` | `process/new/page.tsx` (dedicated process wizard) |
| `/dashboard/structured-descriptions` | present; **commented out of sidebar** |
| `/dashboard/vector-categories` | present; not in sidebar |

### Admin (outside dashboard, gated)

| Route | File |
|-------|------|
| `/admin` | `app/admin/page.tsx` |
| `/admin/users` | `app/admin/users/page.tsx` |
| `/admin/analytics` | `app/admin/analytics/page.tsx` |
| `/admin/billing` | `app/admin/billing/page.tsx` |
| `/admin/logs` | `app/admin/logs/page.tsx` |
| `/admin/stuck-products` | `app/admin/stuck-products/page.tsx` |
| `/admin/settings` | `app/admin/settings/page.tsx` |
| `/admin/bootstrap` | `app/admin/bootstrap/page.tsx` |
| `/admin/migrate-organizations` | `app/admin/migrate-organizations/page.tsx` |
| `/admin/tasks-cleanup` | `app/admin/tasks-cleanup/page.tsx` |

WooCommerce in legacy is **not** a top-level dashboard nav item; it lives under export-feed actions (`components/export-feeds/woocommerce-*.tsx`).

### Legacy sidebar nav (`components/utilities/sidebar.tsx`)

Order: Dashboard → Products → Feeds → Export Feeds → Categories → Attributes → Standard Fields → Background Tasks → Usage & Billing → Settings.

(Structured Fields / WooCommerce / Admin are **not** in this customer sidebar.)

---

## 2. v2 routes (`apps/web/src/routes`)

### Auth

| Route | File |
|-------|------|
| `/login` | `login/+page.svelte` |
| `/register` | `register/+page.svelte` (legacy `/signup`) |
| `/accept-invite` | `accept-invite/+page.svelte` (legacy `/accept-invitation`) |

### App shell

| Route | File |
|-------|------|
| `/` | `+page.svelte` (dashboard home; legacy `/dashboard`) |
| `/products` | `products/+page.svelte` |
| `/feeds` | `feeds/+page.svelte` |
| `/feeds/[feedId]/mapping` | `feeds/[feedId]/mapping/+page.svelte` |
| `/export-feeds` | `export-feeds/+page.svelte` (list **and** create/edit dialog — no `/new` or `/[id]` routes) |
| `/categories` | `categories/+page.svelte` |
| `/categories/[categoryId]/title-formula` | `…/title-formula/+page.svelte` |
| `/categories/[categoryId]/description-formula` | `…/description-formula/+page.svelte` |
| `/attributes` | `attributes/+page.svelte` |
| `/standard-fields` | `standard-fields/+page.svelte` |
| `/processing` | `processing/+page.svelte` |
| `/tasks` | `tasks/+page.ts` only — **307 redirect** → `/processing` |
| `/billing` | `billing/+page.svelte` |
| `/settings` | `settings/+page.svelte` |
| `/woocommerce` | `woocommerce/+page.svelte` (**v2-only** top-level page) |
| `/plans` | `plans/+page.svelte` (not in nav) |
| `/structured-descriptions` | `structured-descriptions/+page.svelte` (not in nav) |
| `/vector-categories` | `vector-categories/+page.svelte` (not in nav) |

### Admin

| Route | File |
|-------|------|
| `/admin` | `admin/+page.svelte` |
| `/admin/users` | `admin/users/+page.svelte` |
| `/admin/analytics` | `admin/analytics/+page.svelte` |
| `/admin/billing` | `admin/billing/+page.svelte` |
| `/admin/logs` | `admin/logs/+page.svelte` |
| `/admin/stuck-products` | `admin/stuck-products/+page.svelte` |
| `/admin/settings` | `admin/settings/+page.svelte` |
| `/admin/bootstrap` | `admin/bootstrap/+page.svelte` |
| `/admin/migrate-organizations` | `admin/migrate-organizations/+page.svelte` |
| `/admin/tasks-cleanup` | `admin/tasks-cleanup/+page.svelte` |

### v2 sidebar nav (`src/lib/components/Nav.svelte`)

Order: Dashboard → Products → Feeds → Export Feeds → Categories → Attributes → Standard Fields → Background Tasks → Usage & Billing → Settings → **WooCommerce** → **Admin**.

Admin link is **always rendered** (not gated by `is_platform_admin`); page gate is client-side via `requirePlatformAdmin()`.

---

## 3. Route / nav comparison matrix

| Capability | Legacy | v2 | Gap |
|------------|--------|----|-----|
| Dashboard home | `/dashboard` | `/` | Path rename only |
| Products | `/dashboard/products` | `/products` | Feature gaps (see P0) |
| Feeds list | `/dashboard/feeds` | `/feeds` | Mostly present |
| Feed mapping (rich) | `/feeds/.../mapping-v2` | `/feeds/.../mapping` | **No mapping-v2 / schema extract / live XML tree** |
| Export list | `/export-feeds` | `/export-feeds` | OK shell |
| Export create/edit | `/export-feeds/new`, `/[feedId]` + `ExportFeedBuilder` | Single-page dialog | **Missing full builder route** |
| Categories + formulas | yes | yes | Bulk Formula stub; double title chrome |
| Attributes | yes | yes | Missing per-attr Manage Categories |
| Standard Fields | yes (live) | shell + “API not available” banner | **Non-functional nav item** |
| Background Tasks | `/tasks` | `/processing` (+ `/tasks` redirect) | Floating task indicator missing |
| Billing / Settings | yes | yes | Close |
| Plans | `/plans` | `/plans` | Shell; API banner |
| Process wizard | `/process/new` | — | **Missing dedicated route** |
| Structured descriptions | route (nav commented out) | route, no nav | Shell; API banner |
| Vector categories | route | route, no nav | Shell; API banner |
| WooCommerce | export-feed dialogs | `/woocommerce` nav item | Different IA; maps UI thin |
| Admin | separate `/admin` layout, not in customer sidebar | always in customer Nav | **IA + visibility gap** |
| Signup | Clerk `/signup` | `/register` | Rename OK |
| Invite | `/accept-invitation` | `/accept-invite` | Rename OK |
| Onboarding tour | `TourProvider` in dashboard layout | — | Missing |

---

## 4. Dialog inventory

### Legacy dialogs (representative)

| Dialog | Path | v2 counterpart |
|--------|------|----------------|
| Export selection (pick export feed) | `components/products/export-selection-dialog.tsx` | **Missing** — CSV download only |
| CSV EAN upload | `components/dashboard/csv-ean-upload-dialog.tsx` | `UploadEansDialog.svelte` |
| Add category attribute (product edit) | `components/dashboard/add-category-attribute-dialog.tsx` | **Missing** |
| Manage categories (per attribute) | `components/attributes/manage-categories-dialog.tsx` + TreeSelect | **Missing** (bulk CSV only) |
| Manage list values | `components/attributes/manage-list-values-dialog.tsx` | Inline dialog in `attributes/+page.svelte` |
| Bulk category↔attribute CSV | `components/attributes/bulk-category-assignments-dialog.tsx` | Inline bulk dialog |
| Bulk formula builder | `components/categories/bulk-formula-builder-dialog.tsx` | **Stub button** (toast message) |
| Field mapping / sync history | `components/feeds/*` | Partial (history dialog exists; mapping preview stub) |
| Export WooCommerce config | `components/export-feeds/woocommerce-integration-dialog.tsx` | Moved to `/woocommerce`; not on export row |
| Standard field / group dialogs | `components/standard-fields/*` | Present in page; **API unavailable** |
| Admin assign/create plan | `components/admin/billing/*` | Admin billing page exists; verify depth |
| Add credits | `components/dashboard/add-credits-dialog.tsx` | Inline on billing page |

### v2 dialogs present under `$lib/components`

Category: `AddCategoryDialog`, `EditCategoryDialog`, `DeleteCategoryDialog`, `TreeSelectDialog`, formula dialogs (`CustomVariableDialog`, `ManageVariablesDialog`, `TextElementDialog`, `ConfirmationDialog`).  
Products: `UploadEansDialog` only.  
UI primitive: `Dialog.svelte`.

Many “dialogs” are inlined in route `+page.svelte` files rather than shared components.

---

## 5. Findings by priority

### P0 — fix before claiming UI cutover readiness

1. **Feed mapping: live XML/CSV schema preview** — **DONE (2026-08-08)**  
   - **v2 now:** `feeds/[feedId]/mapping/+page.svelte` + `FeedSourcePreview` + `MappingPreviewPanel` + `POST /api/feeds/{id}/extract-schema` (click-to-pick path, extract/refresh, sample preview).  
   - Residual polish (CSV column-click pick, legacy mapping-v2 chrome) is P1 — not a cutover blocker.

2. **Export feed create/edit is a thin dialog, not the full builder** — **WAIVED for cutover**  
   - **WAIVER ID:** `DESIGN-P0-EXPORT-BUILDER-2026-08-08`  
   - **v2:** `export-feeds/+page.svelte` in-dialog create/edit (`formRoot` / `formItem` / flat `fields[]`) covers create, edit, refresh, and download for daily ops.  
   - **Deferred:** dedicated `/export-feeds/new` + `/export-feeds/[id]` `ExportFeedBuilder` (structure editor, custom variables, Woo column actions) — large UI port, not required when dialog template editing works.  
   - Re-open only if a tenant needs legacy builder-only flows.

3. **Products “Export Selected” bypasses export feeds**  
   - **v2:** `products/+page.svelte` `exportSelected()` builds a client-side CSV blob and downloads it.  
   - **Legacy:** `ExportSelectionDialog` → choose configured export feed → server export job.  
   - **Wrong:** Wrong UX contract; no feed picker dialog; cannot export via template XML/CSV.

4. **“Reset to Unprocessed” is a stub**  
   - **v2:** `products/+page.svelte` sets `success = "Reset to unprocessed is not available in v2 yet."`  
   - **Legacy:** mutation in `products-client.tsx` calls reset action and updates selection.  
   - **Wrong:** Button appears in `ProductProcessingActions.svelte` but does nothing useful.

5. **Standard Fields API** — **DONE (2026-08-08)**  
   - **v2:** `GET/POST/PATCH/DELETE /api/standard-fields` + `/api/field-groups` (+ bulk-enable / enable-recommended) mounted in `httpapi/server.go`; `standard-fields/+page.svelte` CRUD wired via `apiAvailable`.  
   - Stale “API not available” copy in older checklists no longer applies when the API is up.

6. **Product edit Attributes tab** — **DONE (MVP, 2026-08-08)**  
   - **v2:** `ProductEditPanel` Attributes tab supports add/edit/remove key-value rows; save/accept PATCH includes `attributes` (`UpdateProcessedProduct`).  
   - **Deferred (P1):** legacy `AddCategoryAttributeDialog` (pick from category attribute catalog) — not required for free-form attribute fix-ups.

7. **Attributes: no per-attribute “Manage Categories” / tree assign dialog**  
   - **v2:** Row menu = Edit Details / Manage Values / Delete; bulk CSV assign only (`showBulkAssign`). Unit/example fields in Edit are **disabled**.  
   - **Legacy:** `ManageCategoriesDialog` + TreeSelect + editable unit/example.  
   - **Wrong:** Operators cannot visually assign one attribute to categories without CSV.

8. **Admin Settings / Admin home are UI demos (non-persisting)**  
   - **v2:** `admin/settings/+page.svelte` — `saveDemo(label)` → *“saved (UI demo — not persisted by API yet)”* for General/Security/API/Pricing/Maintenance.  
   - **v2:** `admin/+page.svelte` — *“Admin configuration saved! (UI demo — not persisted…)”*.  
   - **Wrong:** Controls look real; saves are fake.

9. **Admin Logs page has no data path**  
   - **v2:** `admin/logs/+page.svelte` — *“System logs API is not available in v2 yet.”* Table chrome only.  
   - **Wrong:** Nav item under Admin presents empty operational tooling.

10. **Admin always visible in customer sidebar**  
    - **v2:** `Nav.svelte` hardcodes `{ href: "/admin", label: "Admin" }` for every signed-in user.  
    - **Legacy:** Admin is a separate app shell (`app/admin/layout.tsx` + `AdminSidebar`); **not** in `components/utilities/sidebar.tsx`.  
    - **Wrong:** Clutters IA; non-admins hit a gate/error after navigation (misleading).

11. **Categories Bulk Formula Builder is stubbed**  
    - **v2:** `categories/+page.svelte` button sets success message: *“Bulk Formula Builder … is not wired in v2 yet.”*  
    - **Legacy:** `bulk-formula-builder-dialog.tsx` full CSV → AI titles flow.  
    - **Wrong:** Primary page action is decorative.

12. **Floating TaskStatusIndicator** — **DONE (2026-08-08)**  
    - **v2:** `TaskStatusIndicator` mounted from `+layout.svelte` (signed-in, non-auth/marketing/admin); polls `/api/processing/jobs`, shows active job progress + link to `/processing`.  
    - Scope: processing jobs only (feed sync remains on feed row / history — same as existing feeds UX).

---

### P1 — important parity / incomplete dialogs

13. **Dedicated `/process/new` wizard missing**  
    - Legacy: `app/dashboard/process/new/` selects raw products + kicks processing.  
    - v2: processing starts from Products selection only. Dashboard “Start Processing” just `goto("/products")`.

14. **Export list missing WooCommerce column / row actions**  
    - Legacy table: optional WooCommerce status + Configure/Sync actions (`export-feeds-table.tsx`).  
    - v2 table columns: Name, Format, Feed URL, Last Updated, Status, Actions — no Woo column.

15. **Feed source types UX limited to URL CSV/XML**  
    - v2 Add Feed dialog: name + URL + type select (`feeds/+page.tsx`).  
    - Legacy mapping-v2 supports CSV/Excel paths and richer reset/extract; FTP/file upload remain product gaps (also backend).

16. **Categories page double title / spacing**  
    - `PageShell title="Categories"` **and** inner `<h1 class="text-3xl…">Categories</h1>` in `categories/+page.svelte` → duplicated heading and extra vertical space vs legacy single header pattern.

17. **Plans / Structured Descriptions / Vector Categories shells**  
    - Routes exist with legacy-looking UI but API banners (`plans/+page.svelte`, `structured-descriptions/+page.svelte`, `vector-categories/+page.svelte`).  
    - Not in nav (same as legacy for structured), but deep-links look “done” while disabled.

18. **Admin bootstrap is instructional only**  
    - `admin/bootstrap/+page.svelte`: *“Bootstrap is not available via API… set is_platform_admin in DB.”*

19. **WooCommerce rich mapping UI**  
    - `/woocommerce` has config + auto-map buttons, but no legacy-depth mapping table/editor for overrides (status-and-gaps also notes this).

20. **Auth marketing chrome incomplete**  
    - Legacy login: sticky header + **Book a Demo** CTA + privacy/terms links.  
    - v2 auth layout (`+layout.svelte`): logo header + simple footer copyright; no Demo CTA, no privacy/terms routes wired in footer.

21. **Onboarding tour / NavigationProgress missing**  
    - Legacy dashboard layout wraps `TourProvider` + `NavigationProgress`.  
    - v2 layout has neither.

22. **Job/export dialogs from products**  
    - Legacy `job-export-dialog.tsx` for exporting job results.  
    - v2: not found under products components.

23. **Attribute edit: unit & example disabled**  
    - `attributes/+page.svelte` Edit dialog: `editUnit` / `editExample` inputs `disabled` — looks editable in legacy.

24. **NewsFeed “More updates coming soon”**  
    - `NewsFeed.svelte` ends with static “coming soon” — fine as content, but weaker than legacy news richness if operators expect changelog parity.

---

### P2 — polish / low traffic

25. **Path / naming deltas** (`/register` vs `/signup`, `/accept-invite` vs `/accept-invitation`, `/processing` vs `/tasks`) — redirects/docs only.  
26. **Admin migrate-orgs / tasks-cleanup** — pages exist; confirm copy and empty states match legacy density.  
27. **Description/title formula:** drag reorder exists (`FormulaBuilder.svelte` HTML5 DnD); still may lack legacy `@hello-pangea/dnd` polish / edge cases — verify against `title-formula` client before calling pixel-complete.  
28. **Auth card-only main** vs Clerk multi-step branding (intentional first-party auth; visual tone differs).  
29. **No dark-theme admin shell** — legacy admin forces `defaultTheme="dark"`; v2 admin uses same light customer tokens.  
30. **Sign-out placement** — v2 Nav has Sign out under items; legacy relied more on Clerk user button in header (v2 has avatar → settings only).

---

## 6. Known stubs / demo markers (code pointers)

| Location | Marker |
|----------|--------|
| `routes/categories/+page.svelte` | Bulk Formula Builder not wired |
| `routes/products/+page.svelte` | Reset to unprocessed not available |
| `routes/plans/+page.svelte` | Plans API not available |
| `routes/structured-descriptions/+page.svelte` | Structured descriptions API not available |
| `routes/vector-categories/+page.svelte` | Vector categories API not available |
| `routes/admin/settings/+page.svelte` | `saveDemo()` — UI demo |
| `routes/admin/+page.svelte` | UI demo save |
| `routes/admin/logs/+page.svelte` | Logs API not available |
| `routes/admin/bootstrap/+page.svelte` | Bootstrap not available via API |
| `lib/components/NewsFeed.svelte` | “More updates coming soon” |

~~Removed as closed:~~ mapping XML tree placeholder; standard-fields “API not available” (API mounted).

---

## 7. Suggested fix order (UI-only)

1. ~~Feed mapping preview + schema extract UX~~ **DONE**.  
2. ~~ExportFeedBuilder dedicated routes~~ **WAIVED** (`DESIGN-P0-EXPORT-BUILDER-2026-08-08`) — dialog covers daily ops.  
3. Export Selection dialog on products; implement Reset to Unprocessed.  
4. ~~Product edit attribute editing~~ **DONE (MVP)**; Add Category Attribute remains P1.  
5. Attributes Manage Categories (reuse `TreeSelectDialog`).  
6. Gate Admin (and optionally Woo) in `Nav.svelte`.  
7. Replace admin `saveDemo` with real endpoints or disable Save.  
8. Re-enable Bulk Formula Builder dialog.  
9. ~~Port TaskStatusIndicator into `+layout.svelte`~~ **DONE**.  
10. Auth footer links + Demo CTA if marketing parity required.  
11. ~~Standard Fields API~~ **DONE** (handlers mounted).

---

## 8. Out of scope for this audit

Backend/migrator/CI gaps already tracked in [status-and-gaps.md](status-and-gaps.md). This document only covers what users see and click in the web app versus the legacy Next.js UI.