rsspipe/docs/008_desktop_view_feedback_and_specifications.md

008 - Desktop & Mobile View Feedback & Design Specifications

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

---

PART A: Desktop 3-Pane View Specifications

1. Design Aesthetics & Visual Identity

• Theme Palette: Metal-inspired, refined monochrome with sleek slate/zinc surfaces (#09090b, #18181b, #27272a), crisp typography (Inter/system), and dedicated functional 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 (auto_read):

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.

---

PART B: Mobile Waterfall View & Reader Specifications

6. General Layout & Safe Area

• iOS Bottom Bar Safe Area:
  • The 5-button bottom navigation bar (.ios-bottom-nav) is elevated with dedicated safe area breathing room (height: 72px, padding-bottom: calc(16px + env(safe-area-inset-bottom))) above the iOS virtual home bar.
• Top Header Bar Removal:
  • Removed top branding header, search icon, and view switcher to maximize vertical reading canvas on mobile screens.
• Interactive Left-Edge Gesture:
  • Swiping from within 45px of the left screen edge provides interactive horizontal dragging (translateX) with smooth slide-out dismissal animation instead of an abrupt jump.
• Scroll Position Retention:
  • Returning from a post waterfall feed back to the previous list (Subscriptions or Starred) preserves the exact list scroll location.

---

7. Home Tab (Discovery Waterfall)

• Categories Bar at Top:
  • The horizontal scrollable category pill bar sits directly at the top of the Home tab, with the "All" tab active by default.
• Floating Integrated Search Bar:
  • Placed on the same top row as categories on the far right.
  • Tapping the search icon smoothly expands the search bar from right to left with an integrated clear button and auto-focus.
• Pull-to-Refresh & Discovery Reshuffle:
  • Dragging down at the top of the waterfall feed (~1/3 screen threshold) reveals a pull indicator ("Pull down to refresh" ➔ "Release to reload & shuffle").
  • Releasing triggers a refresh and randomly reshuffles post cards for an engaging discovery experience.
• SmartArt Post Cards (No-Image Fallback):
  • For articles without images, SmartArt cards render clean post description text snippets instead of raw article URLs or empty containers.
• Automatic Infinite Scroll:
  • Automatically loads more articles when scrolling to the bottom of the feed.
• Double-Tap Home Tab:
  • Double-tapping the 🏠 Home icon on the bottom navigation bar smoothly scrolls the waterfall feed back to the top.

---

8. Mobile Full-Screen Article Reader (MobileArticleSheet)

Top Navigation Row

• Single-Row Layout (.mobile-sheet-top-nav):
  • [ < Return Button ] [ Feed Favicon ] [ Feed Title ]
  • Eliminates clutter and keeps the feed identity anchored at the top.

Article Content Layout

1. Post Title (h1)
2. Author · Published Date · Estimated Reading Time
────────────────────────────────────────────────────
3. AI Summary Box (Purple theme, copy button)
4. Article Content Body (HTML / Full Text)

No Horizontal Page Scrolling

• Universal horizontal overflow protection (overflow-x: hidden; width: 100%; max-width: 100vw;).
• Forced word wrapping (word-break: break-word; overflow-wrap: anywhere;) on all article canvas text, links, and code blocks to prevent unwrapped URLs from causing horizontal viewport shifts.

Docked Bottom Action Toolbar (.mobile-sheet-bottom-bar)

• Bottom-Left Corner (Action Icons):
  • ⭐ Star: Toggles between empty star and filled Yellow/Gold (#d97706).
  • 🔗 Share: Toggles public share link, copies URL to clipboard with confirmation banner, and highlights in Electric Blue (#2563eb).
  • 🎧 Audio / TTS: Shows in Emerald Green (#059669) with live play/pause control when narration is available.
  • ↗️ Original Link: Opens original web link in a new browser tab.
• Bottom-Right Corner (Popup Split Action):
  • Split button (Get Full Text / Original) with an upward chevron that opens a Dropup Popup Menu:
    • 🔮 Generate AI Summary: Purple (#7c3aed).
    • 🎙️ Generate Audio (TTS): Emerald Green (#059669).

---

9. Harmonized Color Identity System

Feature	Primary Hex Code	CSS Variable / Token	State Appearance
Star / Favorited	#d97706 (Amber/Gold)	--badge-star	Solid filled star
Public Share	#2563eb (Electric Blue)	--badge-shared	Solid blue icon + soft tint background
AI Summary	#7c3aed (Royal Purple)	--badge-ai	Purple icon, border & chip
Audio / TTS	#059669 (Emerald Green)	--badge-tts	Emerald icon + soft green pill
Keywords	#0284c7 (Sky Blue)	--badge-keyword	Sky blue badge chip
Tags	#10b981 (Emerald Green)	--badge-tag	Emerald #tag chip

---

10. Cross-Device Settings & Real-Time Sync

• Server-Side Persistence:
  • All user reading preferences (auto_read, view_preference, theme) are stored in the SQLite users.preferences column via GET/PUT /api/user/preferences.
• Multi-Session Synchronization:
  • Preferences automatically sync with localStorage on session start.
  • Added window focus and tab visibilitychange listeners in App.tsx and SettingsView.tsx, ensuring setting changes made on mobile immediately reflect on desktop when switching windows.