From f4bf9c13e63059d9d7b9b222885cad0a719eb671 Mon Sep 17 00:00:00 2001
From: jamey <jamey@server.jamey.stream>
Date: Sat, 28 Feb 2026 19:48:22 +0000
Subject: [PATCH] add admin UX polish plan from full audit

10 tasks covering unsaved changes warning, block picker
descriptions, sidebar grouping, nav editor labels, inline
page settings, real data preview, and more.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 PROGRESS.md                   |  17 +++++-
 docs/plans/admin-ux-polish.md | 110 ++++++++++++++++++++++++++++++++++
 2 files changed, 124 insertions(+), 3 deletions(-)
 create mode 100644 docs/plans/admin-ux-polish.md

diff --git a/PROGRESS.md b/PROGRESS.md
index 40df874..cd9bd5b 100644
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -30,7 +30,7 @@
 
 Ordered by dependency level — admin shell chain first (unblocks most downstream work).
 
-Plans: [admin-redesign.md](docs/plans/admin-redesign.md) | [admin-font-loading.md](docs/plans/admin-font-loading.md) | [setup-wizard.md](docs/plans/setup-wizard.md) | [setup-and-launch.md](docs/plans/setup-and-launch.md) | [setup-auto-confirm.md](docs/plans/setup-auto-confirm.md) | [email-settings.md](docs/plans/email-settings.md) | [search.md](docs/plans/search.md) | [products-refactor.md](/home/jamey/.claude/plans/snug-roaming-zebra.md) | [shipping-sync.md](docs/plans/shipping-sync.md) | [printful-integration.md](docs/plans/printful-integration.md) | [provider-strategy.md](docs/plans/provider-strategy.md) | [css-migration.md](docs/plans/css-migration.md) | [analytics-v2.md](docs/plans/analytics-v2.md) | [page-builder.md](docs/plans/page-builder.md) | [media-library.md](docs/plans/media-library.md) | [custom-pages.md](docs/plans/custom-pages.md)
+Plans: [admin-redesign.md](docs/plans/admin-redesign.md) | [admin-font-loading.md](docs/plans/admin-font-loading.md) | [setup-wizard.md](docs/plans/setup-wizard.md) | [setup-and-launch.md](docs/plans/setup-and-launch.md) | [setup-auto-confirm.md](docs/plans/setup-auto-confirm.md) | [email-settings.md](docs/plans/email-settings.md) | [search.md](docs/plans/search.md) | [products-refactor.md](/home/jamey/.claude/plans/snug-roaming-zebra.md) | [shipping-sync.md](docs/plans/shipping-sync.md) | [printful-integration.md](docs/plans/printful-integration.md) | [provider-strategy.md](docs/plans/provider-strategy.md) | [css-migration.md](docs/plans/css-migration.md) | [analytics-v2.md](docs/plans/analytics-v2.md) | [page-builder.md](docs/plans/page-builder.md) | [media-library.md](docs/plans/media-library.md) | [custom-pages.md](docs/plans/custom-pages.md) | [admin-ux-polish.md](docs/plans/admin-ux-polish.md)
 
 | # | Task | Depends on | Est | Status |
 |---|------|------------|-----|--------|
@@ -98,8 +98,8 @@ Plans: [admin-redesign.md](docs/plans/admin-redesign.md) | [admin-font-loading.m
 | ~~87~~ | ~~`FaviconController` serving all favicon routes + dynamic `site.webmanifest`; `<link>` tags + `theme-color` meta in `shop_root.html.heex`~~ | 86 | 1.5h | done |
 | ~~88~~ | ~~SVG dark mode injection for SVG-source favicons; icon background colour + short name customisation~~ | 86 | 1h | done |
 | | **No-JS support** | | | |
-| 56 | Audit all key flows for no-JS (browse, cart, checkout, analytics) | — | 2h | planned |
-| 57 | Fix any broken flows for no-JS clients | 56 | TBD | planned |
+| ~~56~~ | ~~Audit all key flows for no-JS (browse, cart, checkout, analytics)~~ | — | 2h | done |
+| ~~57~~ | ~~Fix any broken flows for no-JS clients~~ | 56 | TBD | done |
 | | **SEO** | | | |
 | ~~58~~ | ~~Page titles with separators across all pages~~ | — | 1h | done |
 | ~~59~~ | ~~Open Graph + Twitter Card meta tags (products, collections, home)~~ | 58 | 2h | done |
@@ -127,6 +127,17 @@ Plans: [admin-redesign.md](docs/plans/admin-redesign.md) | [admin-font-loading.m
 | 90 | Instrument existing event points — stripe webhook, OrderNotifier, OrderSubmissionWorker, fulfilment status, ProductSyncWorker | 89 | 1.5h | planned |
 | 91 | Order timeline component on `/admin/orders/:id` — chronological feed replacing scattered field cards | 89 | 1.5h | planned |
 | 92 | Global `/admin/activity` LiveView — all activity + "needs attention" tab, resolve action, count badge on admin nav | 89 | 2h | planned |
+| | **Admin & page editor UX polish** ([plan](docs/plans/admin-ux-polish.md)) | | | |
+| 103 | Unsaved changes warning — `beforeunload` + LiveView nav guard on page editor | — | 30m | planned |
+| 104 | Block descriptions in picker — add subtitle text to each block type | — | 45m | planned |
+| 105 | Sidebar nav grouping — section headers or nest Email/Redirects under Settings | — | 45m | planned |
+| 106 | Nav editor input labels — visible labels above each input pair | — | 30m | planned |
+| 107 | Custom page settings inline — collapsible panel in editor instead of separate page | — | 1h | planned |
+| 108 | Preview with real data — load actual products/categories instead of PreviewData | — | 45m | planned |
+| 109 | Block content preview in list — one-line summary below block name | — | 45m | planned |
+| 110 | "Providers" label clarity — rename to "Print providers" in sidebar | — | 5m | planned |
+| 111 | Newsletter block backend — wire up email collection or mark as decorative | — | 1-3h | planned |
+| 112 | Block preview thumbnails in picker — small illustrations per block type | — | 2h | planned |
 | | **Other features** | | | |
 | ~~72~~ | ~~Order status lookup — wire up existing stub on contact page (UI already exists, backend unbuilt)~~ | — | 1.5h | done |
 | | **Abandoned cart recovery** ([plan](docs/plans/abandoned-cart.md)) | | | |
diff --git a/docs/plans/admin-ux-polish.md b/docs/plans/admin-ux-polish.md
new file mode 100644
index 0000000..3a2960f
--- /dev/null
+++ b/docs/plans/admin-ux-polish.md
@@ -0,0 +1,110 @@
+# Admin & page editor UX polish
+
+Status: Planned
+
+## Context
+
+Full UX audit of the admin panel and page editing experience, evaluating intuitiveness, completeness, and newbie-friendliness. The admin is solid and well-built — good accessibility, clear status indicators, logical flow. The gaps are around preventing data loss, helping newbies understand block types, and tidying up navigation.
+
+## What works well
+
+- Dashboard launch checklist with direct links to each setup step
+- Split-screen page editor with live preview, undo/redo, keyboard shortcuts
+- ARIA labels on all block controls, live region announcements
+- Clear dirty state tracking (badge + disabled save button)
+- Legal page auto-population with "auto-generated" vs "customised" badges
+- Live editing on shop pages via sidebar with same block card UI
+- Custom page creation with templates (blank/content/landing)
+- Shop header shows "Edit page" and "Admin" icons for logged-in admins
+- Settings page with status pills and helpful setup guidance
+
+## Tasks
+
+### High priority
+
+#### 1. Unsaved changes warning
+**Problem:** No `beforeunload` handler or LiveView navigation guard. Clicking "Pages" breadcrumb or any sidebar link silently discards all unsaved changes.
+**Fix:** Add a `beforeunload` event listener in the `EditorKeyboard` JS hook that checks `data-dirty`. Also handle LiveView `phx-remove` / navigation events to warn before leaving.
+**Files:** `assets/js/hooks/editor_keyboard.js`, possibly `lib/berrypod_web/live/admin/pages/editor.ex`
+**Est:** 30m
+
+#### 2. Block descriptions in picker
+**Problem:** Block picker shows icon + name only. "Info card" vs "Trust badges" vs "Image + text" — a newbie doesn't know what these do or look like.
+**Fix:** Add a `description` field to each block type in `BlockTypes`. Show it as a subtitle in the picker modal.
+**Files:** `lib/berrypod/pages/block_types.ex`, `lib/berrypod_web/components/block_editor_components.ex`
+**Est:** 45m
+
+### Medium priority
+
+#### 3. Sidebar nav grouping
+**Problem:** 12 top-level items in the admin sidebar is too flat. Dashboard, Analytics, Orders, Products, Providers, Pages, Navigation, Media, Theme, Settings, Email, Redirects — a wall of links with no visual hierarchy.
+**Fix:** Add subtle section headers to group related items:
+- **Shop** — Dashboard, Analytics, Orders, Products, Providers
+- **Content** — Pages, Navigation, Media
+- **Appearance** — Theme
+- **Settings** — Settings, Email, Redirects
+
+Alternatively, nest Email under Settings (it's email *settings*) and move Redirects into a Settings sub-page. That drops to 10 items with clearer grouping.
+**Files:** `lib/berrypod_web/components/layouts/admin.html.heex`, `assets/css/admin/components.css`
+**Est:** 45m
+
+#### 4. Nav editor input labels
+**Problem:** Navigation editor shows pairs of text inputs with placeholder text ("Label", "/path") but no visible labels. Accessibility issue and confusing for new users.
+**Fix:** Add visible `<label>` elements above each input pair, or at minimum a row header like "Link 1", "Link 2". Consider showing a small preview of each link.
+**Files:** `lib/berrypod_web/live/admin/navigation.ex`
+**Est:** 30m
+
+#### 5. Custom page settings inline
+**Problem:** Clicking "Settings" on a custom page editor navigates away to `/admin/pages/:slug/settings`, losing editing context. Round-tripping between editor and settings is jarring.
+**Fix:** Show page settings (title, slug, meta description, published, show in nav) in a collapsible panel at the top of the editor, or in a slide-over panel. Keep the separate settings page as a fallback but make inline editing the default.
+**Files:** `lib/berrypod_web/live/admin/pages/editor.ex`
+**Est:** 1h
+
+#### 6. Preview with real data
+**Problem:** Admin editor preview uses `PreviewData` (fake products, fake cart). The user's actual products don't appear. This means the preview doesn't accurately represent the live shop. The live editor on shop pages uses real data and doesn't have this problem.
+**Fix:** Load real products/categories/cart from the database for preview, falling back to `PreviewData` if no products exist yet (fresh install). This makes the admin preview match what the shop actually looks like.
+**Files:** `lib/berrypod_web/live/admin/pages/editor.ex` (mount, preview_pane)
+**Est:** 45m
+
+### Low priority
+
+#### 7. Block content preview in list
+**Problem:** Block settings are hidden behind a gear icon toggle. The block list is just type names with position numbers — no indication of content. You can't scan and see "this hero says 'Welcome to my shop'" without expanding each block.
+**Fix:** Show a one-line content preview below the block name (e.g. first text field value, truncated). Only for blocks that have text settings.
+**Files:** `lib/berrypod_web/components/block_editor_components.ex` (block_card)
+**Est:** 45m
+
+#### 8. "Providers" label clarity
+**Problem:** "Providers" is jargon. A newbie selling mugs doesn't know what a "provider" is in this context.
+**Fix:** Rename to "Print providers" in the sidebar. Consider "Suppliers" as an alternative. Update the nav label only — the route and module names can stay as-is.
+**Files:** `lib/berrypod_web/components/layouts/admin.html.heex`
+**Est:** 5m
+
+#### 9. Newsletter block backend
+**Problem:** The newsletter signup form renders on the shop but has no backend handler. A user adds it to their page thinking it works, then discovers email signups go nowhere.
+**Fix:** Either: (a) wire up a simple email collection table + controller so signups are stored, or (b) add a note in the block settings saying "Coming soon — this block is currently decorative" and mark it visually in the editor.
+**Files:** TBD depending on approach
+**Est:** 1-3h depending on approach
+
+#### 10. Block preview thumbnails in picker
+**Problem:** Block picker shows names and descriptions (after task 2) but no visual preview. Users still have to guess what blocks look like.
+**Fix:** Add a small screenshot or SVG illustration for each block type in the picker. Could be static images stored in `priv/static/images/blocks/`.
+**Files:** `lib/berrypod_web/components/block_editor_components.ex`, static assets
+**Est:** 2h (mostly creating the images)
+
+## Summary table
+
+| # | Task | Priority | Est |
+|---|------|----------|-----|
+| 1 | Unsaved changes warning | High | 30m |
+| 2 | Block descriptions in picker | High | 45m |
+| 3 | Sidebar nav grouping | Medium | 45m |
+| 4 | Nav editor input labels | Medium | 30m |
+| 5 | Custom page settings inline | Medium | 1h |
+| 6 | Preview with real data | Medium | 45m |
+| 7 | Block content preview in list | Low | 45m |
+| 8 | "Providers" label clarity | Low | 5m |
+| 9 | Newsletter block backend | Low | 1-3h |
+| 10 | Block preview thumbnails | Low | 2h |
+
+Total: ~8-10h across all tasks