haopengzhan/rsspipe
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
271a542196f41a60c6625fcda72f5347130f2f3a
rsspipe/docs/007_ui_ux_architecture_and_design_specification.md
T

16 KiB
Raw Blame History

007 - UI/UX Architecture & Design Specification

This document details the complete design, layout philosophy, component hierarchy, gesture system, and CSS token architecture for RSSPipe's renewed frontend.

1. Design Philosophy & System Architecture

RSSPipe follows a dual-mode philosophy: Power-Desk Reader for large desktop screens / tablets and Xiaohongshu-style Visual Discovery Feed for mobile devices. Rather than forcing a single responsive compromise, the application decouples into two purpose-built consumption systems sharing core backend state, authentication, and settings.

graph TD
    A[App Shell / Router] --> B{Platform & Width Detection}
    B -->|Screen >= 768px & Pointer| C[Desktop 3-Split System]
    B -->|Screen < 768px or Touch| D[Mobile Waterfall System]
    B -->|Manual Toggle / Hotkey 'V'| E[View Mode Override]
    C --> F[Draggable 3-Column Workspace]
    D --> G[iOS Bottom Nav + Masonry Grid]
    C --> H[Shared Core Services & State]
    D --> H
    H --> I[Settings, Auth, Modals, Audio Engine]

1.1 Platform & View Mode Resolution

  1. Initial Resolution:
    • Touch Detection: 'ontouchstart' in window || navigator.maxTouchPoints > 0
    • Viewport Width: window.innerWidth < 768
    • If either condition is true and no prior manual user preference exists in localStorage, default to waterfall. Otherwise, default to split.
  2. Persistence:
    • Stored under localStorage.getItem('rsspipe_view_mode').
    • Desktop header contains an explicit switch button; pressing V (when not focused in an input) toggles between split and waterfall.

2. Design System & CSS Token Architecture

RSSPipe adopts a high-contrast, clean minimalist Light Mode design language inspired by Apple Human Interface Guidelines and Linear.app.

2.1 CSS Layering & File Structure

Styles are organized into modular, maintainable stylesheets loaded in dependency order:

web/src/styles/
├── tokens.css       # Core variables: colors, typography, elevations, radiuses, z-indices
├── base.css         # Reset, typography, app container, custom micro-scrollbars
├── three-pane.css   # 3-split layout, draggable splitter handles, desktop list, power reader
├── waterfall.css    # Mobile bottom nav, masonry grid, SmartArt cards, swipe sheets
├── settings.css     # Restrained, harmonized settings panels (AI, Rules, Feeds)
└── modals.css       # Shared dialogs (Add Feed, OPML Import/Export, Keyboard Shortcuts)

2.2 Formal Design Tokens (tokens.css)

:root {
  /* Surface & Background */
  --bg-app: #f8fafc;
  --bg-surface: #ffffff;
  --bg-sidebar: #f8fafc;
  --bg-card: #ffffff;
  --bg-card-hover: #f1f5f9;
  --bg-card-active: #e2e8f0;
  --bg-subtle: #f1f5f9;

  /* Borders */
  --border-light: #f1f5f9;
  --border-subtle: #e2e8f0;
  --border-strong: #cbd5e1;
  --border-focus: #0f172a;

  /* Typography */
  --font-sans: 'Inter', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;

  /* Text Colors */
  --text-primary: #0f172a;
  --text-secondary: #334155;
  --text-muted: #64748b;
  --text-dim: #94a3b8;
  --text-inverse: #ffffff;

  /* Brand Accents */
  --accent-primary: #0f172a;
  --accent-hover: #1e293b;
  --accent-soft: rgba(15, 23, 42, 0.05);
  --accent-border: #cbd5e1;

  /* Semantic Colors */
  --star-gold: #d97706;
  --star-bg: #fef3c7;
  --success: #15803d;
  --danger: #b91c1c;
  --badge-ai: #4f46e5;
  --badge-tts: #0284c7;

  /* Radius */
  --radius-xs: 4px;
  --radius-sm: 6px;
  --radius-md: 10px;
  --radius-lg: 16px;
  --radius-full: 9999px;

  /* Elevations */
  --shadow-xs: 0 1px 2px rgba(0, 0, 0, 0.03);
  --shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.05), 0 1px 2px rgba(0, 0, 0, 0.03);
  --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.06);
  --shadow-lg: 0 12px 28px rgba(0, 0, 0, 0.1);
  --shadow-docked: 0 -4px 16px rgba(0, 0, 0, 0.05);

  /* Layout Dimensions */
  --header-height: 48px;
  --bottom-nav-height: 56px;
  --docked-audio-height: 52px;
  --sidebar-min-width: 200px;
  --sidebar-default-width: 240px;
  --list-min-width: 280px;
  --list-default-width: 380px;
  --reader-min-width: 480px;
}

3. Desktop 3-Split System Specification

The Desktop 3-Split experience is optimized for speed, precision, and power keyboard navigation.

+-----------------------------------------------------------------------------------------+
| [Header]: RSSPipe | Filter / Search | View Toggle (V) | Add Feed | User Profile        |
+--------------------+-----------------------------+--------------------------------------+
| SIDEBAR (Resizable)| ARTICLE LIST (Resizable)    | DETAIL READER (Fluid)                |
|                    |                             |                                      |
| 📥 Inbox (12)      | [🔍 Search / Filter Pills ] | [Action Toolbar: Star, Read, AI, TTS]|
| ⭐ Starred (4)     | [Compact / Card Mode Toggle]| ==================================== |
| 🏷️ Tech & AI (8)   | +-------------------------+ | <h1>Article Title</h1>               |
|   - Hacker News (5)| | [Unread Dot] Feed Title   | <p>Source: Hacker News • 2h ago</p>   |
|   - Ars Technica(3)| | Post Headline Title       |                                      |
| ⚙️ Settings        | | 2h ago • 3 min read       | [AI Summary Box (Collapsible)]       |
|                    | +-------------------------+ |                                      |
|                    | | Next Article Row...     | [Markdown / Full-Text Content Body]  |
| <Drag Handle 1>    | <Drag Handle 2>             |                                      |
+--------------------+-----------------------------+--------------------------------------+

3.1 Draggable Resizable Panes

  • Handle Component: ResizableSplitter listens to mousedown, mousemove, mouseup on window with an invisible overlay prevent-iframe-drag.
  • Constraints:
    • Pane 1 (Sidebar): 180px min, 400px max. Double-click handle collapses/expands sidebar ([ key shortcut).
    • Pane 2 (List): 260px min, 600px max.
    • Pane 3 (Reader): Takes remaining fluid width (flex: 1, min-width: 400px).
  • Width Persistence: Saved in localStorage under rsspipe_pane_widths: { sidebar, list }.

3.2 List Mode Toggle (Compact vs Rich Cards)

  • Compact Mode: 2-line condensed rows with unread dot, source title, post headline, and relative time. Maximizes scan speed (30+ posts visible per screen).
  • Rich Card Mode: Includes 1-line summary snippet, cover thumbnail (if present), tags, and reading time.

3.3 Desktop Power Reader Toolbar

  • Variant Selector: Original RSS / Readability Scraped / AI Translated / Plain Text.
  • AI Summary Pill: Collapsible summary panel with bulleted highlights.
  • Scrape Full-Text Button: Triggers Readability fetch with live spinner.
  • Audio TTS Player: Inline audio bar with play/pause and progress scrubber.
  • Actions: Star (s), Mark Unread (m), Open in Browser (o), Copy Link.

3.4 Keyboard Shortcuts (Vim / Superhuman Style)

Active exclusively in Desktop 3-Split mode:

Shortcut Action
j / ↓ Select next article in list
k / ↑ Select previous article in list
m / r Toggle Read / Unread status
s Toggle Star / Bookmark
f Fetch / Scrape full-text content
a Toggle AI Summary expansion
o / v Open original article in external tab
[ Collapse / Expand Sidebar
/ Focus search input field
? Show Keyboard shortcuts modal

4. Mobile Waterfall System Specification (Xiaohongshu-Style)

The Mobile Waterfall experience is designed for thumb-driven browsing, rich visual exploration, and native-feeling gesture interactions.

+------------------------------------------+
|  [Header]: RSSPipe         [🔍 Search]   |
+------------------------------------------+
|  [Tabs]: All | Tech | News | Science     |
+------------------------------------------+
|  WATERFALL MASONRY GRID (2-Column)       |
|                                          |
|  +----------------+  +----------------+  |
|  | [Image / Cover]|  | [SmartArt Text]|  |
|  | Headline text  |  | Headline text  |  |
|  | that wraps 2-3 |  | in high-style  |  |
|  | lines...       |  | typography     |  |
|  | [Favicon] Feed |  | [Favicon] Feed |  |
|  +----------------+  +----------------+  |
|  +----------------+  +----------------+  |
|  | [SmartArt Text]|  | [Image / Cover]|  |
|  | ...            |  | ...            |  |
|  +----------------+  +----------------+  |
+------------------------------------------+
| [Docked Mini Audio Player] (If Playing)  |
+------------------------------------------+
| [iOS Bottom Nav]: 🏠Home|📡Feeds|🎧Listen|⭐Starred|⚙️Settings |
+------------------------------------------+

4.1 iOS 5-Tab Bottom Navigation Bar (XHSBottomNav)

Fixed to the bottom viewport (height: 56px, backdrop-filter: blur(20px), border-top: 1px solid var(--border-subtle)):

  1. 🏠 Home:
    • 2-column masonry waterfall of all incoming posts (weighted/curated discovery).
    • Top header displays minimal RSSPipe branding and a Search button icon (🔍).
  2. 📡 Feeds:
    • Clean source directory grouped by Category.
    • Shows feed favicon, title, unread count badge, and health status.
    • Tapping a feed navigates to a dedicated single-feed waterfall view with a top "← Back to Feeds" header.
  3. 🎧 Listen:
    • Filtered waterfall containing only posts with playable audio/TTS/podcast variants.
    • Cards display audio duration badge (🎧 4 min) and 1-tap quick play button.
  4. ⭐ Starred:
    • Feeds and folder list containing starred items with star badge counts.
    • Tapping opens the filtered Starred posts waterfall.
  5. ⚙️ Settings:
    • Mobile-adapted profile, feeds manager, AI rules, and OPML import/export.

4.2 Card Design & SmartArt Typographic Covers

  • Posts with Images: Image rendered at natural aspect ratio with subtle rounded corners (border-radius: 8px).
  • Posts without Images (SmartArt Cover):
    • Generates a styled visual banner using subtle mathematical gradient seeds based on feed name.
    • Large expressive serif/sans quote typography displaying the first 6-10 words of the title or excerpt.
    • Eliminates dull empty gray boxes while maintaining fast pure-CSS rendering.
  • Card Footer:
    • Source favicon / initial avatar.
    • Clean truncated feed title.
    • Relative time (2h ago) or Star icon.

4.3 Mobile Full-Screen Article Reader (MobileArticleSheet)

  • Open Transition: Tapping a card smoothly mounts the full-screen reading sheet with iOS slide-up transition (transform: translateY(0)).
  • Navigation Gestures:
    • Left-Edge Swipe to Dismiss: User drags from the left edge (0px - 30px boundary) towards the right to swipe away the article back to the waterfall grid.
    • No horizontal page skipping: Prevents accidental article skipping while scrolling long texts.
    • Vertical Scrolling: Standard elastic touch scrolling with high-legibility font sizing (17px body, 1.6 line height).
  • Mobile Action Pill: Floating or top-bar minimal actions (Star, Audio Play, Share, Open in Browser). AI summaries and Readability variants are pre-generated by server rules and rendered inline.

4.4 Docked Mobile Audio Player (DockedAudioPlayer)

  • Docked Bar: When audio/TTS is playing, docks directly above the Bottom Navigation Bar (bottom: 56px):
    • Mini cover art / favicon.
    • Scrolling title + feed name.
    • 15s Rewind (⏪), Play/Pause (⏯️), 15s Fast-forward (⏩), Close (✕).
    • 2px slim live progress line at the top edge of the player.
  • Expanded Player Modal: Tapping the mini-player expands into a full modal sheet:
    • Large cover art / SmartArt illustration.
    • Full-width scrubber slider with current time and remaining time.
    • Playback speed switcher (0.75x, 1.0x, 1.25x, 1.5x, 2.0x).
    • Bulleted AI highlights / transcript view.

5. Harmonized Settings Design System

Settings panels (especially AI Rules, Prompt Engineering, and Triage) are refactored from disparate dense layouts into the unified minimal design system:

  • Navigation Sidebar: Left list on desktop, top tab pill bar on mobile.
  • Section Grouping:
    • Feeds & Folders: Feed subscription list, category organization, OPML export.
    • AI & Automation: Provider configuration (OpenAI, Gemini, Ollama, DeepSeek), automated scraping rules, TTS voice selection.
    • Preferences: Default view mode, reading font size, auto-mark read on scroll.
  • Form Controls: Consistent 40px input height, subtle border-focus outline, clean toggle switches, minimal action buttons.

6. Directory Structure & Component Map

web/src/
├── App.tsx                        # Master shell, view mode resolution, global audio state
├── types.ts                       # Shared interfaces and types
├── utils.ts                       # Formatters, text extractors, SmartArt seed generators
├── services/
│   └── api.ts                     # REST API client
├── styles/
│   ├── tokens.css                 # [NEW] Design variables
│   ├── base.css                   # [NEW] Baseline typography & layout
│   ├── three-pane.css             # [NEW] Desktop split panes & splitters
│   ├── waterfall.css              # [NEW] Mobile waterfall & bottom nav
│   ├── settings.css               # [NEW] Harmonized settings styles
│   └── modals.css                 # [NEW] Modal dialog styles
└── components/
    ├── common/
    │   ├── Header.tsx             # Shared top header
    │   ├── LoginView.tsx          # Login & session initiation
    │   ├── AddFeedModal.tsx       # New feed modal dialog
    │   ├── OPMLModal.tsx          # OPML import/export modal
    │   └── KeyboardShortcutsModal.tsx # Shortcut cheat sheet
    ├── desktop/
    │   ├── ThreePaneView.tsx      # 3-column container with draggable splitters
    │   ├── ResizableSplitter.tsx  # Drag handle component
    │   ├── DesktopSidebar.tsx     # Feeds, categories, and inbox folder tree
    │   ├── DesktopArticleList.tsx # List column with Compact/Card toggle
    │   └── DesktopReader.tsx      # Desktop reader pane with power toolbar
    ├── mobile/
    │   ├── WaterfallView.tsx      # Mobile waterfall root container
    │   ├── XHSBottomNav.tsx       # iOS-style 5-tab bottom navigation
    │   ├── MobileArticleSheet.tsx # Slide-in reader with left-edge swipe dismiss
    │   ├── SmartArtCard.tsx       # Typographic cards for image-less posts
    │   ├── DockedAudioPlayer.tsx  # Sticky mini player + expanded player sheet
    │   ├── FeedsTabView.tsx       # Feeds & category directory tab
    │   └── StarredTabView.tsx     # Starred feeds directory tab
    └── settings/
        └── SettingsView.tsx       # Unified minimal settings view

7. Implementation Milestones

  1. Milestone 1: Design Tokens & Modular CSS Foundation:
    • Create tokens.css, base.css, three-pane.css, waterfall.css, settings.css, modals.css.
    • Update main.tsx / index.html to import the new style system.
  2. Milestone 2: Desktop 3-Split System:
    • Implement ResizableSplitter and update ThreePaneView.
    • Add Compact List vs Rich Card toggle.
    • Implement Vim keyboard shortcuts (j/k, m, s, [).
  3. Milestone 3: Mobile Waterfall & iOS Bottom Navigation:
    • Implement XHSBottomNav with the 5 tabs (Home, Feeds, Listen, Starred, Settings).
    • Create SmartArtCard for image-less posts.
    • Build MobileArticleSheet with left-edge touch swipe-to-dismiss gesture.
  4. Milestone 4: Docked Mobile Audio Player:
    • Build DockedAudioPlayer for TTS/podcast playback with docked mini-bar and expandable sheet.
  5. Milestone 5: Harmonize Settings & Shared Modals:
    • Refactor SettingsView (AI, Rules, Feeds) to use clean design tokens.
    • End-to-end responsive & touch testing.
Reference in New Issue View Git Blame Copy Permalink