Newsletter-Link-Catalog/notes/UI Spec.md

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.