JakeBreath/J621
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity
Files
3f353307cf83241c73c1802c6050327f59083210
J621/frontend/DESIGN.md
T
JakeBreath 555c25d77b 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
2026-09-17 07:56:47 -05:00

249 lines
12 KiB
Markdown
Raw Blame History

---
name: Mocha Archive Terminal
colors:
surface: '#121221'
surface-dim: '#121221'
surface-bright: '#383849'
surface-container-lowest: '#0d0d1c'
surface-container-low: '#1a1a2a'
surface-container: '#1e1e2e'
surface-container-high: '#292839'
surface-container-highest: '#333344'
on-surface: '#e3e0f7'
on-surface-variant: '#cdc3d1'
inverse-surface: '#e3e0f7'
inverse-on-surface: '#2f2f40'
outline: '#968e9a'
outline-variant: '#4a444f'
surface-tint: '#d9b9ff'
primary: '#e2c7ff'
on-primary: '#3f1e66'
primary-container: '#cba6f7'
on-primary-container: '#57377f'
inverse-primary: '#704f98'
secondary: '#a8c8ff'
on-secondary: '#003062'
secondary-container: '#124988'
on-secondary-container: '#8fbaff'
tertiary: '#c8ceff'
on-tertiary: '#212c62'
tertiary-container: '#a8b2f1'
on-tertiary-container: '#39437a'
error: '#ffb4ab'
on-error: '#690005'
error-container: '#93000a'
on-error-container: '#ffdad6'
primary-fixed: '#eedbff'
primary-fixed-dim: '#d9b9ff'
on-primary-fixed: '#290350'
on-primary-fixed-variant: '#57377f'
secondary-fixed: '#d5e3ff'
secondary-fixed-dim: '#a8c8ff'
on-secondary-fixed: '#001b3c'
on-secondary-fixed-variant: '#0e4685'
tertiary-fixed: '#dee0ff'
tertiary-fixed-dim: '#bac3ff'
on-tertiary-fixed: '#09154c'
on-tertiary-fixed-variant: '#38437a'
background: '#121221'
on-background: '#e3e0f7'
surface-variant: '#333344'
typography:
headline-xl:
fontFamily: Inter
fontSize: 2rem
fontWeight: '700'
lineHeight: 2.5rem
letterSpacing: -0.02em
headline-lg:
fontFamily: Inter
fontSize: 1.5rem
fontWeight: '600'
lineHeight: 2rem
letterSpacing: -0.015em
headline-sm:
fontFamily: Inter
fontSize: 1.125rem
fontWeight: '600'
lineHeight: 1.5rem
letterSpacing: -0.01em
body-lg:
fontFamily: Inter
fontSize: 1rem
fontWeight: '400'
lineHeight: 1.5rem
body-md:
fontFamily: Inter
fontSize: 0.875rem
fontWeight: '400'
lineHeight: 1.25rem
body-sm:
fontFamily: Inter
fontSize: 0.75rem
fontWeight: '400'
lineHeight: 1rem
label-md:
fontFamily: JetBrains Mono
fontSize: 0.8125rem
fontWeight: '500'
lineHeight: 1.125rem
label-sm:
fontFamily: JetBrains Mono
fontSize: 0.6875rem
fontWeight: '500'
lineHeight: 0.875rem
code-md:
fontFamily: JetBrains Mono
fontSize: 0.8125rem
fontWeight: '400'
lineHeight: 1.25rem
code-sm:
fontFamily: JetBrains Mono
fontSize: 0.6875rem
fontWeight: '400'
lineHeight: 1rem
rounded:
sm: 0.125rem
DEFAULT: 0.25rem
md: 0.375rem
lg: 0.5rem
xl: 0.75rem
full: 9999px
spacing:
gutter: 0.75rem
margin: 1rem
space-xs: 0.25rem
space-sm: 0.5rem
space-md: 0.75rem
space-lg: 1rem
space-xl: 1.5rem
---
## Brand & Style
This design system establishes a high-density, terminal-adjacent archival workspace tailored for local storage utilities, self-hosted media indexers, and massive metadata catalogs.
The aesthetic synthesizes modern utilitarian minimalism with tactical developer tool ergonomics. It prioritizes information density, deterministic navigation, and prolonged visual comfort during low-light browsing sessions. Interfaces built with this system feel swift, local-first, engineered, and rigorously organized. Visual noise is aggressively suppressed; structure is created via layered dark surfaces and strict typographical hierarchies rather than decorative borders or heavy drop shadows. High-saturation taxonomy accents serve strictly semantic duties—routing the eye through deep tag trees, cryptographic checksums, storage volumes, and safety ratings without fatigue.
## Colors
The palette is rooted in a layered, warm-tinted dark foundation with functional chromatic categorization.
### Surface Architecture
- **Crust (`#11111b`)**: Global structural chrome, status bars, and deepest canvas sinks.
- **Mantle (`#181825`)**: Application rails, persistent panels, toolbars, and primary viewport backgrounds.
- **Base (`#1e1e2e`)**: Active work surfaces, content display fields, and preview canvas.
- **Surface0 (`#313244`)**: Interactive container backings, inactive input wells, and resting component boundaries.
- **Surface1 (`#45475a`)**: Hover highlights, subtle interior structural lines, and elevated tooltips.
- **Surface2 (`#585b70`)**: Active selection states, focused borders, and drag handles.
### Text & Iconography
- **Text (`#cdd6f4`)**: High-contrast body copy, active inputs, and primary values.
- **Subtext1 (`#bac2de`)**: Secondary labels, section headers, and active state indicators.
- **Subtext0 (`#a6adc8`)**: Metadata keys, column identifiers, and timestamps.
- **Overlay0 (`#6c7086`)**: Placeholder text, inactive controls, disabled states, and structural icon fills.
### Accents & Rating Semantics
- **Mauve (`#cba6f7`)**: Primary action intent, keyboard focus triggers, and copyright categorization.
- **Blue (`#89b4fa`)**: Navigational links, dynamic filtering, informational highlights, and general taxonomy.
- **Lavender (`#b4befe`)**: Tertiary controls, filter operators, and logical modifiers.
- **Green (`#a6e3a1`)**: Safe rating (`s`), verified file integrity, matches, and success responses.
- **Peach (`#fab387`)**: Questionable rating (`q`), unverified states, warnings, and species taxonomy.
- **Red (`#f38ba8`)**: Explicit rating (`e`), destructive actions, corruption alerts, and blacklist locks.
- **Yellow (`#f9e2af`)**: Starred items, bookmarked queries, and artist taxonomy.
### Metadata Taxonomy Roles
Tag tokens apply foreground colors paired with 10% opacity tints of the same hue on `Surface0` backgrounds:
- **Artist**: `#f9e2af`
- **Copyright**: `#cba6f7`
- **Character**: `#a6e3a1`
- **Species**: `#fab387`
- **General**: `#89b4fa`
- **Meta**: `#9399b2`
## Typography
Typography establishes an intentional contrast between narrative/UI structural elements (`Inter`) and raw data points (`JetBrains Mono`).
### Rules & Application
- Use `Inter` for layout hierarchy, navigation labels, button labels, modal headers, and descriptive UI documentation.
- Use `JetBrains Mono` strictly for:
- Cryptographic hashes (MD5, SHA-256).
- Storage paths, pool directories, and UNIX file permissions.
- Tag token text and tag post-counts.
- File resolutions (e.g., `3840x2160`), bitrates, color spaces, and file sizes.
- Post IDs, internal sequence counters, and UTC timestamps.
- Tabular figures (`tnum`) must be enforced globally for `JetBrains Mono` to ensure that vertical numerical data columns remain aligned across dense table and sidebar views.
## Layout & Spacing
The layout model is driven by a flexible, high-density utility grid designed to adapt between deep media discovery canvases and compact metadata inspection panels.
### Layout Model
- **Inspector Layout**: A persistent 3-tier layout consisting of a fixed 64px left global navigation rail, an auto-collapsible 260px metadata hierarchy sidebar, and an auto-fitting masonry/grid canvas.
- **Fluid Canvas**: Media grids adjust from 2 to 8 columns based on thumbnail zoom sliders, using CSS Grid with dynamic `minmax()` constraints and a standardized `0.75rem` (`gutter`) boundary.
- **Compact Padding**: Interactive components employ compressed internal metrics (`space-xs` and `space-sm`) to maximize visible information density per vertical screen inch.
### Responsive Breakpoints
- **Mobile (< 768px)**: Metadata panels collapse into a sliding bottom drawer. The media grid fixes to a 2-column layout with `0.5rem` gutters and `0.75rem` outer canvas margins.
- **Tablet (768px - 1024px)**: Left rail persists. Sidebar transitions to an overlay toggle. Media grid utilizes 3 to 4 fluid columns.
- **Desktop (> 1024px)**: Full multi-pane viewport. Three columns: Navigation/Filter sidebar (280px), Content stream (fluid), and Active Item Inspector (340px, collapsible).
## Elevation & Depth
Visual depth is achieved through **tonal layering** and **subtle surface borders**, completely avoiding heavy drop shadows to retain a crisp, utilitarian screen presence.
### Depth Hierarchy
- **Level 0 (Canvas Base)**: `Crust (#11111b)` forms the base environment underneath all views and side navigation wells.
- **Level 1 (Structural Paneling)**: `Mantle (#181825)` elevated above Crust, partitioned with a 1px solid `Surface0 (#313244)` edge.
- **Level 2 (Containers & Cards)**: `Base (#1e1e2e)` for post cards, table rows, and media backings. Uses 1px `Surface0 (#313244)` outline.
- **Level 3 (Interactive Floating Wells)**: Dropdown menus, contextual popovers, and quick-tag menus sit on `Surface0 (#313244)` with a 1px border of `Surface1 (#45475a)` and a 4px ambient tint: `box-shadow: 0 4px 12px rgba(17, 17, 27, 0.6)`.
Focus states reject fuzzy drop shadows in favor of a crisp 2px offset outline using `Mauve (#cba6f7)`.
## Shapes
This design system uses a **Soft (`roundedness: 1`)** geometry specification (baseline `0.25rem` / 4px, `rounded-lg` at `0.5rem` / 8px).
- **Micro Controls**: Checkboxes, tag badges, status pills, and thumbnail corner overlays use strict `0.25rem` radii.
- **Standard Controls**: Inputs, buttons, segmented selectors, and dropdown triggers use `0.375rem` (6px).
- **Major Containers**: Media cards, modal dialogs, storage pool panels, and image viewing canvases use `0.5rem` (`rounded-lg`).
- **Pill Shapes (`9999px`)**: Reserved exclusively for safety rating badges (`Safe`, `Questionable`, `Explicit`) and active search-token pills in the omnibar.
## Components
### Buttons
- **Primary**: Background `Mauve (#cba6f7)`, text `Crust (#11111b)`, font `Inter` semibold. Hover: lightens brightness by 10%. Active: scales down to `0.98`. Focus: 2px ring of `Mauve` with a 2px `Base` gap.
- **Secondary/Ghost**: Background `Surface0 (#313244)`, text `Text (#cdd6f4)`, border 1px solid `Surface1 (#45475a)`. Hover: background `Surface1 (#45475a)`.
- **Destructive**: Background `transparent`, text `Red (#f38ba8)`, border 1px solid `Red` at 40% opacity. Hover: background `Red` at 15% opacity.
### Chips & Taxonomy Badges
- **Tag Badges**: Mono-font (`JetBrains Mono`), `0.6875rem`, letter-spacing normal.
- Structure: A 1px border matching the taxonomy category color at 30% opacity, background set to category color at 10% opacity, text set to the pure category color.
- Hover: Background shifts to 20% opacity; shows append/negate controls (`+`, `-`).
- **Rating Pills**: Compact badges positioned over thumbnails or in item manifests.
- `Safe`: Text `Crust`, background `Green (#a6e3a1)`.
- `Questionable`: Text `Crust`, background `Peach (#fab387)`.
- `Explicit`: Text `Crust`, background `Red (#f38ba8)`.
### Input Fields & Omnibar
- **Resting**: Background `Mantle (#181825)`, border 1px solid `Surface0 (#313244)`, text `Text (#cdd6f4)`, placeholder `Overlay0 (#6c7086)`. Font: `JetBrains Mono` for syntax inputs, `Inter` for general forms.
- **Focused**: Border color `Mauve (#cba6f7)`, background `Base (#1e1e2e)`, box-shadow `0 0 0 1px #cba6f7`.
- **Tag Autocomplete Inputs**: Displays color-coded prefixes (`artist:`, `series:`, `md5:`) matching taxonomy tokens within the text caret flow.
### Media Cards
- **Shell**: Background `Base (#1e1e2e)`, border 1px solid `Surface0 (#313244)`, overflow hidden.
- **Image Frame**: Center-cropped preview with an aspect ratio of 1:1 in grid mode.
- **Card Overlays**: Hover reveals a `Mantle (#181825)` gradient at the bottom containing file dimensions, extension label (e.g., `WEBM`, `PNG`), and file size in `JetBrains Mono` sm. Top corners feature safety rating pill (left) and favorite/star status (right).
### Checkboxes & Radio Elements
- **Box**: 14x14px, background `Mantle (#181825)`, border 1px solid `Surface2 (#585b70)`, border radius 3px.
- **Checked**: Background `Mauve (#cba6f7)`, border `Mauve (#cba6f7)`, checkmark icon tinted `Crust (#11111b)`.
### Data Tables & Lists
- **Rows**: Alternating stripes of `Base (#1e1e2e)` and `Mantle (#181825)`. Border bottom 1px solid `Surface0 (#313244)`.
- **Row Hover**: Background `Surface0 (#313244)` at 50% opacity.
- **Cell Metric Formatting**: Aligned right for sizes, IDs, and dimensions; formatted using `JetBrains Mono`.
### Storage & Pool Indicators
- **Capacity Bars**: 4px high track in `Surface0 (#313244)`, fill color defaults to `Blue (#89b4fa)`. Transitions to `Peach (#fab387)` at 80% capacity and `Red (#f38ba8)` at 95% capacity.
Reference in New Issue View Git Blame Copy Permalink