berrypod/docs/plans/admin-ux-polish.md

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