J621/frontend/design.md_j621_frontend_spec.md

DESIGN.md — J621 Frontend Design System & Architecture Specification

Version: 1.4.2-stable
Theme Foundation: Catppuccin Mocha + e621 Authentic Taxonomy Architecture
Target Platform: Desktop-first, fully responsive self-hosted home-server media web application (the library is a watched folder on disk, not a NAS appliance)
Reference Design System: Mocha Archive Terminal ({{DATA:DESIGN_SYSTEM:DESIGN_SYSTEM_3}})

---

1. Visual Language & Foundation

The visual identity of J621 blends a high-density, pro-tier terminal aesthetics (inspired by modern system monitors and desktop DAM software) with the Catppuccin Mocha palette and authentic e621.net color-coded taxonomy standards.

1.1 Color Palette Tokens

:root {
  /* Surface Layers (Catppuccin Mocha) */
  --bg-crust:    #11111b; /* Outer frame, status strips, sticky bottom bars */
  --bg-mantle:   #181825; /* Panels, sidebars, modal surfaces, table headers */
  --bg-base:     #1e1e2e; /* Primary canvas & workspace background */
  --surface-0:   #313244; /* Cards, inputs, table rows, neutral borders */
  --surface-1:   #45475a; /* Hover states, active borders, elevated chips */
  --surface-2:   #585b70; /* Active button states, selected boundaries */

  /* Text & Typography */
  --text-primary:   #cdd6f4; /* High-contrast body, primary titles */
  --text-subtext1:  #bac2de; /* Secondary labels, active badges */
  --text-subtext0:  #a6adc8; /* Metadata captions, counters */
  --text-overlay0:  #6c7086; /* Disabled states, placeholders, icons */
  --text-overlay1:  #7f849c; /* Subtle metadata */

  /* Brand & Core Accents */
  --accent-mauve:     #cba6f7; /* Primary brand accent, active tabs, buttons */
  --accent-mauve-dim: rgba(203, 166, 247, 0.15); /* Tinted selection pill */
  --accent-lavender:  #b4befe; /* Secondary links & focus rings */
  --accent-teal:      #94e2d5; /* System online indicators, verified states */
  --accent-blue:      #89b4fa; /* Primary links, remote indicators */

  /* Status & Severity */
  --status-success:   #a6e3a1; /* Safe rating, verified checksums, healthy */
  --status-warning:   #fab387; /* Questionable rating, pending warnings */
  --status-danger:    #f38ba8; /* Explicit rating, blacklisted items, errors */
  --status-highlight: #f9e2af; /* Followed stars, active favorites */
}

---

2. e621 Authentic Taxonomy Color Specification

All tag chips, counters, and sidebar taxonomy badges strictly adhere to e621's established namespace semantics mapped to Mocha tokens:

Namespace	Mocha Token	Hex Code	UI Semantic Usage
Artist	Yellow / Gold	#f9e2af	Creators, animators, illustrators
Copyright	Mauve / Purple	#cba6f7	Franchises, studios, properties (e.g. Pokemon, Nintendo)
Character	Green	#a6e3a1	Named characters (Krystal, Fox McCloud)
Species	Peach / Orange	#fab387	Biological species, body forms (Jolteon, Canine, Dragon)
General	Sky Blue	#89b4fa	Action, posture, apparel, thematic tags (solo, clothed, bag)
Meta	Subtext / Slate	#9399b2	Resolution, digital specs, years (hi_res, 2026, webm)
Lore	Teal	#94e2d5	Fictional universe lore and faction metadata
Invalid / Blacklist	Red	#f38ba8	Filtered content, blacklisted rules, dangerous operations

---

3. Rating & Moderation Semantics

• Safe (S): Tagged with #a6e3a1 (Green). 1px border on gallery cards, badge background rgba(166, 227, 161, 0.15).
• Questionable (Q): Tagged with #fab387 (Peach/Amber). 1px border, badge background rgba(250, 179, 135, 0.15).
• Explicit (E): Tagged with #f38ba8 (Red). 1px border, badge background rgba(243, 139, 168, 0.15).
• Blacklisted Overlay: Filtered pools/tags replace the preview with a dark container (#11111b), a red ban shield icon (#f38ba8), and explicit Bypass & Reveal or Manage Filter options.

---

4. Layout & Information Architecture

4.1 Global Frame (Shell)

• Top App Bar (#11111b, height: 56px):
  • Left: Brand mark J621 badge (#cba6f7) followed by the storage line — the path of the watched folder that J621 indexes (e.g. /mnt/media/library). J621 is folder-based: this is just a path on disk, not a NAS/appliance indicator.
  • Center: Nav pills: Library, Online, Pools, Followed, Upload, Duplicates, and Stats [STAFF].
  • Right: System status pill with real backend values, never hardcoded: environment (DEV/PROD), the actual host OS, page generation time, and the total e621 API request time for that page load — e.g. ENV: PROD · LINUX · 18ms (e621: 4ms). Followed by the user avatar.
• Global Footer Status Strip (#11111b, height: 32px):
  • The strip placement is a proposal; its values are real and drawn from the existing stats data.
  • Left: the watched folder path — 📁 Local Storage: /mnt/media/library.
  • Center: ⚡ Active Workers: N running | Queue: M pending — the count of active optimization/ingest jobs and queued downloads (the original app surfaced this on its stats page; the footer simply keeps it visible).
  • Right: the build actually running — J621 <version> / commit hash.
• Collapsible Sidebar (Behavior):
  • Closed by default across all gallery and viewer views to prioritize screen real estate.
  • Toggled via ☰ button or quick keyboard shortcut (Ctrl+B or ⌘B).
  • On mobile/tablet viewports (< 1024px), opens as an overlay modal drawer with backdrop blur.

---

5. Screen Component Catalog

5.1 Library Main Gallery

• Header Filters: Search query input with autocomplete (filename:, tag:, score:, rating:), items-per-page selector (24, 48, 96), and sorting dropdown (Date Added, Filesize, Post ID).
• Media Card Grid: CSS Grid (grid-template-columns: repeat(auto-fill, minmax(220px, 1fr))).
• Card Specs:
  • Rating corner indicator ribbon (S, Q, E).
  • Sync verification icon (✓ Ingested).
  • Monospace footer: #<post_id> · <filesize> · <score> ▲ <faves> ★ <comments> 💬.

5.2 Library & Online Detail View (e621 Aligned)

• 2-Column Layout:
  • Left Rail (320px): Categorized tag hierarchy (Artist, Copyright, Species, General, Meta) with tag search links ? and follow + toggles. Specs sheet (Post ID, MD5, dimensions, format, source URL).
  • Right Main Area:
    • Action Header: Download (local files) / Download to Library (online posts), Favorite, Add to Pool — downloading writes into the watched folder; there is no separate "NAS" step. Favorites and pools are e621-side actions.
    • Media Canvas: Centered high-resolution image or loopable WebM/MP4 viewer with pan/zoom.
    • Context Panels: Artist commentary, local storage allocation paths (/data/media/j621/...), inode/checksum integrity report, and user comment stream.

5.3 Upload & Ingestion Pipeline

• Dropzone: Drag-and-drop target with support for PNG, JPG, WEBM, MP4, GIF (up to 512MB).
• 3-Column Board:
  1. Pending & Unmatched: Local uploads awaiting e621 ID link or custom tag specification.
  2. Visual Similarity Detected: Perceptual hash clash resolution (side-by-side diff with replacement or duplicate-keep buttons).
  3. Auto-uploaded & Indexed: Files verified by MD5 or IQDB and written to the archive.

5.4 Duplicates & Similarity Engine

• MD5 Exact Match Section: Hash collision certainty (100%), 1-click Keep File A & Delete File B.
• Perceptual Similarity Groups: Confidence bar (e.g. 96%), side-by-side artwork previews with crop/resolution indicators, and Commit Deduplication queue.

5.5 Followed Tags & Pools

• Subscription Cards: Multi-post collage or tag cover, Unseen Badge (14 Unseen, 99+ Unseen), follow/unfollow toggle star, and Mark Seen button.

5.6 Staff System & Backend Statistics

• Telemetry Cards: AMD Ryzen CPU load/temp gauge, ECC RAM allocation bar, ZFS NVMe pool usage, NVIDIA NVENC hardware acceleration status.
• Worker Pipeline: 4 active background parsing threads with job IDs and operations (pHash, BLAKE3, e621_api).
• Live Terminal Log: Monospace tail container with autoscroll toggle and log level highlighting ([INFO], [INGEST], [API]).

---

6. Implementation Notes for Frontend Engineers

1. State Persistence: Sidebar open/closed state, active rating filter toggles, and items-per-page must persist in localStorage.
2. Smooth Layout Shift Prevention: Preload image dimension aspect ratios (aspect-ratio: attr(width) / attr(height)) to prevent grid jumping during infinite scroll or pagination loads.
3. Keyboard Accessibility:
   • /: Focus search bar
   • Ctrl+K / ⌘K: Quick command palette & tag finder
   • [ / ]: Previous / Next post in detail view
   • D: Trigger Download (or "Download to Library" while browsing online posts)
   • F: Toggle favorite / follow