M0: scaffold SPA + API monorepo
Backend (Django 6.1 + DRF): - Token auth with a custom User model (register/login/logout/me) - Library models (MediaItem, MediaLocation) and REST endpoints - File list/detail with search, rating filter, sorting, pagination - Multipart upload with optional rating/tags/notes - Range-aware media serving (video seeking) and ffmpeg thumbnails - scan_files management command for the watched folder Frontend (React 19 + Vite + TypeScript): - Catppuccin Mocha design tokens from the design docs - App shell, token persistence, protected routes - Library grid with filters, file detail with custom data editor - Upload page with per-file progress via XHR - Dev proxy to the Django API
This commit is contained in:
@@ -0,0 +1,142 @@
|
||||
# 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 NAS / Home Server Media Web Application
|
||||
> **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` badge with `NAS UI` tag).
|
||||
- Center: Nav pills: `Library`, `Online`, `Pools`, `Followed`, `Upload`, `Duplicates`, and `Stats [STAFF]`.
|
||||
- Right: System latency pill (`ENV: PROD · LINUX · 18ms (e621: 4ms)`), user avatar.
|
||||
- **Global Footer Status Strip (`#11111b`, height: 32px):**
|
||||
- Left: `📁 Local Storage: /data/media/j621/archive`
|
||||
- Center: `⚡ Active Workers: 4 Parsing | Sync Queue: 0 Pending`
|
||||
- Right: `J621 Engine v1.4.2-stable`
|
||||
- **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 to Local Library`, `Write to NAS`, `Favorite`, `Add to Pool`.
|
||||
- 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 / Ingest to NAS"
|
||||
- `F`: Toggle favorite / follow
|
||||
Reference in New Issue
Block a user