feat: add newsletter UI implementation plan and UI spec documentation

2026-05-17 15:28:52 -05:00
parent 7da885ed25
commit f4ff04f92b
2 changed files with 158 additions and 0 deletions
@@ -0,0 +1,88 @@
+# Newsletter Link Catalog UI Spec
+
+## Goal
+
+Create a clean, functional web UI for browsing the SQLite-backed newsletter catalog. The UI should feel like a focused database browser: fast to scan, easy to filter, and useful before visual polish.
+
+## Layout
+
+Use a two-pane catalog layout.
+
+### Left Pane: Newsletter Navigation
+
+- Narrow column on desktop.
+- Contains a newsletter search field at the top.
+- Shows a scrollable list of newsletters below the search.
+- Each newsletter item should show:
+  - Newsletter name.
+  - Optional short description or source email when available.
+  - Compact counts such as issues, links, and sponsored links.
+- The currently selected newsletter should have a clear selected state.
+
+### Right Pane: Newsletter Detail
+
+- Shows details for the selected newsletter.
+- Defaults to the most recent issue only to reduce cognitive load.
+- Header should show:
+  - Newsletter name.
+  - Optional description/source email.
+  - Latest issue date.
+  - Counts for the displayed issue.
+- Links should be displayed in a scannable table or grouped list.
+- Link rows should include:
+  - Title.
+  - Category.
+  - Description.
+  - URL.
+  - Also In, when available.
+- Links should be clickable and open in a new tab using `target="_blank"` and `rel="noopener noreferrer"`.
+
+## Issue Scope Controls
+
+The right pane defaults to **Latest Issue**.
+
+Provide a clear control to switch to **All Issues** for the selected newsletter. In All Issues mode:
+
+- Show links from every issue for the selected newsletter.
+- Include issue date on each row.
+- Keep the same search/filter controls.
+- Make it easy to return to Latest Issue mode.
+
+## Global Navigation
+
+Provide lightweight navigation for:
+
+- Dashboard.
+- Newsletters.
+- All Links.
+- Sponsored Links.
+- Dead Links.
+- Runs.
+
+The Newsletter view should be the primary working screen.
+
+## Search and Filters
+
+- Newsletter search filters the left pane immediately.
+- Link search filters the right pane within the selected newsletter and current issue scope.
+- Category filtering should be available in the right pane.
+- Date filtering is only needed in All Issues mode.
+- Empty states should explain what is missing:
+  - No newsletters imported yet.
+  - No links for the selected newsletter.
+  - No matches for the current search/filter.
+
+## Theme and Responsiveness
+
+- Dark mode should be the default visual direction.
+- Respect system preference where practical.
+- Provide a light mode option.
+- Mobile layout should collapse the left pane into a drawer, dropdown, or stacked selector.
+- The UI should remain usable on small screens without horizontal scrolling for core actions.
+
+## Visual Style
+
+- Clean, restrained, and operational.
+- Avoid marketing-style hero sections.
+- Prioritize readable tables/lists, clear selected states, and compact metadata.
+- UI polish can remain minimal for the first implementation, but spacing, contrast, and text wrapping should be professional.