# 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.