JakeBreath
3f353307cf
- 'NAS UI' tag was a misinterpretation of the watched-folder path; the spec now calls it the storage line and notes J621 is folder-based - Status pill documents the real backend fields: environment, actual host OS, page generation time, e621 API request time - Footer strip is marked as a proposal; the workers count is real data from the stats page, not invented thread counts - Removed the remaining 'Write to NAS' / 'Ingest to NAS' phrasing
144 lines
8.8 KiB
Markdown
144 lines
8.8 KiB
Markdown
# 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
|
|
|
|
```css
|
|
: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
|