rsspipe/docs/008_desktop_view_feedback_and_specifications.md

008 - Desktop 3-Pane View Feedback & Design Specifications

This document comprehensively records all user feedback, UX directives, and architectural decisions made for the Desktop 3-Pane View in RSSPipe.

---

1. Design Aesthetics & Visual Identity

• Theme Palette: Metal-inspired, refined monochrome with sleek slate/zinc surfaces (#09090b, #18181b, #27272a), crisp typography (Inter/system), and subtle color accents (Gold for Starred, Emerald for Tags, Blue for Keywords/AI).
• Surface Elevation: Clean hairline borders (1px solid var(--border-subtle)), eliminating heavy shadows or dated blue-gray tints.

---

2. Top Header Bar

Element	Specification & User Directive	Status
Brand & Icon	RSSPipe logo and brand name anchored at the leftmost position across all views.	Implemented
Search Bar	Widened search input with auto-completion backed by search_history database table (keyword, last_searched_at, search_count).	Implemented
Refresh Button	Smooth keyframe rotation animation with guaranteed visual feedback duration on click/poll.	Implemented
Left Sidebar Toggle	Removed from top header (sidebar remains permanently accessible in 3-pane desktop).	Implemented
View Switcher	Removed "3-connected-button" switcher from top bar; view modes configured via Settings > General.	Implemented

---

3. Left Sidebar (Navigation Pane)

Structure & Hierarchy

1. Views Section:
   • Inbox (Unread count badge)
   • Starred (Starred count badge)
   • All Articles
   • Shared (Public share count badge)
2. Feeds Section:
   • Category Folders with nested feeds
   • Uncategorized feeds at root level

UI / UX Rules

• Category Chevron Alignment: Fold/unfold toggle icon is placed immediately after the category title (before the unread count), ensuring category feeds and uncategorized feeds share the exact same left margin and indentation.
• Unread Badges: Pinned flush to the far right edge of the item row.
• Feed Spacing: Tight, efficient vertical spacing (gap: 1px, min-height: 28px).
• Feed Favicons:
  • Automatically resolved from website root (https://www.google.com/s2/favicons?domain=...&sz=64) upon subscription.
  • Rendered with live error fallback to the default RSS icon.
  • Fully customizable in Settings > Feeds > Edit Feed.

---

4. Middle Pane (Article List)

Mode 1: Compact List (compact)

• Row Structure (2-Line):
  • Line 1: Article Headline (entry.title)
  • Line 2: Published Date (YYYY-MM-DD) + right-aligned conditional icons.
• Conditional Status Icons:
  • ⭐ Starred: Gold star button (rendered only when starred; 0px width when unstarred).
  • 🔗 Shared: Share2 icon (rendered only when share_uuid exists).

Mode 2: Expanded / Non-Compact List (rich)

• Strict Rule: No thumbnail images in entry cards.
• Row Structure:
  • Line 1: :title (Article headline)
  • Line 2: :description (Clean text snippet, stripped HTML)
  • Line 3: :date (YYYY-MM-DD left-aligned) + right-aligned status indicators (starred, shared, ai-summarized).
  • Line 4: :keywords and :tags in distinct colors (Blue keyword chips, Emerald #tag chips).

Scope & Filtering

• Dynamic Header Title: Updates to show active feed name, category title, or search query.
• Scope Toggle: [ Unread | All ] pill switcher when browsing a specific feed/category.
• Query Reset: Automatically resets search queries upon selecting a feed/category to prevent "no articles found" confusion.

---

5. Right Pane (Reading Canvas)

Top Action Toolbar

• Left Group:
  • Toggle Unread
  • Toggle Star
  • Toggle Shared (auto-copies link to clipboard)
  • Copy Link
  • Open Original Site (new tab)
• Right Group:
  • Split Action Button:
    • Default click: Get Full Text (scrapes via Readability and switches view to cleaned full text; toggles between Original Feed and Full Text).
    • Dropdown menu: Generate AI Summary and Generate Audio.
  • No extraneous public share link buttons in top menu.

Article Content Layout & Ordering

1. Feed Subtitle + Favicon (feed_title)
2. Post Title (h1)
3. Author (if exists)
4. Updated Date (YYYY-MM-DD HH:mm) • Reading Time
5. Keywords Chips (if exists)
6. Tags Chips (if exists)
──────────────────────────────────────────────────── (Divider)
7. AI Summary Card (in-page error notice if failed)
8. Audio Narration Player (if generated)
9. Article Content Body (HTML / Full Text)

Layout & Scrollbar

• Far-Right Scrollbar: The scroll container spans the full pane width so the native scrollbar sits against the far right edge of the screen, while article content remains centered at a readable max-width (760px).
• AI Summary Error Notice: In-page error banner within the summary container instead of modal alert() popups.

Automatic Read Triggers

When the reading preference is enabled (rsspipe_auto_read_scroll):

1. Short Articles (Content ≤ 1 Page): Automatically marked as read after staying on the article for 3 seconds.
2. Content Click: Clicking anywhere inside the reader content canvas (excluding the toolbar) immediately marks as read.
3. Long Articles (Content > 1 Page): Scrolling down the right reading pane immediately marks as read.

---

6. Real-Time State Synchronization

• Sidebar Counts: Toggling is_read, is_starred, or share_uuid immediately triggers a stats reload to keep sidebar counters (inbox, starred, shared) synchronized in real time.
• Persistence: Switching feeds or categories in the sidebar updates the middle article list without abruptly reloading or clearing the active reading canvas.