warpbox-dev/docs/Design Docs/Ok, where's the .md document for me to look at_ I.md

Ok, where's the .md document for me to look at? I need a comprehensive, deep look into the UI/UX style/design. Write it for me

Here’s the full markdown document for the Warpbox.dev UI/UX design and style guide. You can copy this into a .md file as‑is.

---

Warpbox.dev UI/UX Design & Style Guide

This document defines the user interface (UI) and user experience (UX) guidelines for Warpbox.dev across all stages of the product (anonymous uploads, accounts, admin, embeds, ShareX, scaling, theming). It is intended for designers and developers implementing the web frontend and any graphical configuration or integration tools.

Warpbox.dev should feel:

• Minimal and modern.
• Fast and responsive.
• Obvious for first‑time users.
• Powerful and efficient for advanced users.

Modern self‑hosted file sharing tools like Cloudreve, Zipline, Erugo, and similar projects are praised for a clean, streamlined UI, drag‑and‑drop uploads, and predictable dashboards; Warpbox.dev’s design should follow those expectations.^{1 2 3}

---

1. Global UX Principles

1. Simplicity over feature density
   • Each screen has one primary purpose (e.g., upload, browse, administer) with one clearly dominant action.
   • Secondary actions are available but visually subdued.
2. Progress and feedback everywhere
   • Any long‑running operation (uploads, deletions, archive generation, thumbnailing) displays visible progress and completion status.
   • Use inline progress bars and toast notifications for success/failure.
3. Predictable navigation and structure
   • Users should always know:
     • Where they are (anonymous view, user dashboard, admin area).
     • How to go “home”.
     • How to sign in/out.
   • Navigation labels and locations must remain consistent across pages.
4. Mobile‑first and responsive
   • All core workflows (upload, view, browse, share, basic admin tasks) must work comfortably on mobile phones.
   • Layouts degrade gracefully to single‑column views; tables become lists/cards.
5. Accessible by default
   • Keyboard navigable: all interactive elements reachable via Tab/Shift+Tab.
   • Visible focus states; do not remove the outline.
   • Color contrast meets WCAG AA for text and interactive elements.
   • Use semantic HTML and ARIA roles for complex components (dialogs, nav, tabs).
6. Configurable branding, consistent structure
   • Colors, logos, and text copy can be themed per instance, but:
     • Layout patterns (where nav is, how tables look) stay consistent.
     • Core component behavior (upload component, file lists, drawers, dialogs) does not change between instances.
7. Low cognitive load for first‑time users
   • Use plain, descriptive labels (“Upload files”, “Copy link”, “New folder”) rather than jargon.
   • Keep advanced options behind a clearly labeled “Advanced options” section.

---

2. Global Layout, Navigation, and Visual Language

2.1 Application Shell

Warpbox.dev uses a common shell across authenticated views, with a simplified variant for anonymous users.

Header (top bar):

• Left:
  • Brand logo (or wordmark).
  • Instance name (e.g., “warpbox.dev” or custom brand).
• Center:
  • Contextual page title (“Upload files”, “My files”, “Admin dashboard”).
• Right:
  • Primary navigation and user menu:
    • Anonymous: “About”, “Docs”, “Login”, “Register”.
    • Authenticated: icons + labels for Notifications (optional) and a user avatar / initial that opens a dropdown (“Profile”, “Settings”, “Logout”).

Content area:

• Fixed max width (e.g., 1200–1280px) centered on large screens, full width on mobile.
• Main content column with optional left sidebar:
  • User dashboard/admin: sidebar for navigation + main content.
  • Anonymous landing: no sidebar; main content centered and focused on upload.

Footer:

• Instance details (version, host).
• Links: “Terms of Service”, “Privacy Policy”, “Contact”.
• Optional small tagline or “Powered by Warpbox.dev”.

2.2 Navigation Patterns

Anonymous users:

• Top navigation only:
  • Logo → landing/upload page.
  • “About” → short description page.
  • “Docs” → documentation site.
  • “Login” / “Register” → auth screens.

Authenticated users (regular):

• Left sidebar (desktop) or slide‑out drawer (mobile) containing:
  • Dashboard (default after login).
  • My files.
  • Shared links (optional, later stage).
  • Settings.
  • “Admin” (only visible if user has admin role).

Admin users:

• Within Admin area, the sidebar includes:
  • Overview.
  • Files.
  • Users.
  • Storage.
  • Settings.
  • Logs.

Use icons plus text (“Files”, “Users”) rather than icons alone.

2.3 Visual Language

Typography:

• Use a single, clean sans‑serif stack:
  • Example: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif.
• Base font size: 16px; small text no smaller than 13–14px.
• Headings:
  • Page titles: 24–32px.
  • Section headings: 18–22px.

Color system:

• Primary color: used for:
  • Primary buttons.
  • Selected navigation items.
  • Progress bars.
• Neutral greys:
  • Light background (#f5f5f5–#fafafa).
  • Cards (#ffffff) with subtle shadows or borders.
  • Dividers and table borders (#e5e5e5–#dddddd).
• Semantic colors:
  • Success (green) for completed uploads or successful actions.
  • Warning (amber) for impending expiration, quota usage.
  • Error (red) for failures and destructive actions.

Buttons and controls:

• Primary button: filled, uses primary color.
• Secondary button: outline or ghost style.
• Destructive button: red filled or outlined, clearly distinct.
• Inputs:
  • Label above the field.
  • Helper text and inline error message below.

Components:

• Cards: used for metrics, quick links, file summaries.
• Tables: used for lists of files/users/logs on desktop.
• List or card layouts: used for files on mobile.

---

3. Per‑Stage UI/UX Specification

This section ties UI/UX decisions directly to each implementation stage.

3.1 Stage 1 – Minimal Anonymous Upload MVP

Goal: A first‑time visitor should be able to upload and share a file in seconds without an account.

3.1.1 Landing / Upload Page

Layout:

• Full‑height viewport with content vertically centered.
• A single, prominent upload card:
  • Large drop zone:
    • Icon (e.g., cloud with arrow).
    • Primary text: “Drop files to upload”.
    • Secondary text: “or click to browse”.
    • Dashed border and subtle hover state.
  • Below the drop zone:
    • “Upload limits” micro‑panel:
      • “Max file size: X GB”.
      • “Link expires after Y days”.
    • This panel uses muted colors to avoid competing with the drop zone.

Behavior:

• Drag‑over feedback:
  • Entire drop zone highlights with primary color border.
  • Text may change to “Release to upload”.
• On file selection:
  • Show a list (vertical) of pending files:
    • Name.
    • Size.
    • Progress bar.
  • As each file finishes:
    • Replace progress bar with:
      • Direct link field (read‑only text).
      • “Copy link” button (obvious icon and label).
• Empty state:
  • When no uploads: display only drop zone and small explanatory text.

Error and feedback:

• If file exceeds max size:
  • Inline error row under that file: “This file exceeds the maximum allowed size.”
• If network error:
  • Toast notification: “Upload failed, please try again.” with retry button for the file if possible.

Consistency with tools like Erugo and Zipline (prominent drag‑and‑drop upload, simple layout, clear share link) is intentional, as these interfaces tend to receive positive feedback for usability.^{2 3}

---

3.2 Stage 2 – Robust Anonymous Mode and Housekeeping

Goal: Anonymous upload mode becomes production‑worthy, with advanced options and basic operational views.

3.2.1 Enhanced Upload Options

Add an “Advanced options” panel below the drop zone:

• Collapsed by default; label: “Advanced options”.
• When expanded, show:
  • Expiration:
    • Label: “Expires in”.
    • Dropdown: “1 day”, “7 days”, “30 days”, “Custom”.
  • Max downloads:
    • Numeric input (optional).
    • Helper text: “Leave empty for unlimited downloads until expiration.”
  • Password:
    • Password field with “Show” toggle.
    • Helper text: “Recipients must enter this password to download.”

These options reflect highly requested features in self‑hosted tools (expiry, password, download limit).⁴

3.2.2 Post‑Upload Summary

After successful uploads:

• Display a success card at the top:
  • Title: “Upload complete”.
  • Summary:
    • “3 files uploaded.”
    • “Expires in 7 days, max 10 downloads per link.”
  • Action buttons:
    • “Copy all links”.
    • “Upload more” (secondary).

Below, show individual file rows with:

• File name and size.
• Direct link.
• Buttons: “Copy link”, “Open”.

3.2.3 Basic Anonymous Metrics (Operator View)

Introduce a very simple admin view (even before full admin stage) accessible only to admin users:

• Metrics cards:
  • Total files.
  • Total storage used.
  • Uploads in last 24h.
• Recent uploads table:
  • Columns: Time, File/Bucket ID, Size, IP (masked), Status.
  • Actions: “View”, “Delete”.

This mirrors common UX patterns in dashboards for tools like Cloudreve and Zipline (metric cards + table of recent activity).^{3 1}

---

3.3 Stage 3 – User Accounts and Simple Folders

Goal: Provide a persistent personal space with minimal friction.

3.3.1 Authentication Screens

Login / Register pages:

• Centered card layout against a simple background.
• Elements:
  • Logo + instance name.
  • Title: “Sign in” or “Create account”.
  • Fields:
    • Email.
    • Password (+ confirm for registration).
  • Buttons:
    • Primary action.
    • Link to switch between login/register.
    • Link to go back to home/upload page.

Validation errors appear inline below fields, not in alerts.

3.3.2 User Dashboard (Flat Collections)

After login, route to “Dashboard”:

Layout:

• Sidebar:
  • “Dashboard”.
  • “My files”.
  • “Settings”.
  • “Admin” (if role).
• Main content:
  • Top row:
    • Page title: “My files”.
    • Primary button: “Upload” (opens upload overlay or reuses drop zone at top of page).
  • File list table:
    • Columns: Name, Collection, Size, Uploaded, Actions.
    • Row actions: “View”, “Rename”, “Move (collection)”, “Delete”.

Empty state:

• When user has no files:
  • Illustration or icon.
  • Text: “You have no files yet.”
  • Button: “Upload your first file”.

The goal is a lightweight “personal file library” similar to lightweight alternatives to Nextcloud that people often praise for being less cluttered.¹

---

3.4 Stage 4 – Full Folder Hierarchy and File Metadata

Goal: Upgrade from flat collections to a robust folder tree and search.

3.4.1 Folder Tree and Breadcrumbs

Desktop layout:

• Left column (min-width ~240px):
  • “My files” root node.
  • Expandable tree of nested folders (chevrons for expand/collapse).
• Main area:
  • Breadcrumb at top: My files / Projects / Client A.
  • Toolbar:
    • “New folder”.
    • “Upload”.
    • “Share” (for current folder).
  • Content:
    • First row: folders (as cards or rows).
    • Then: files.

Mobile layout:

• Folder tree becomes:
  • A “Folders” button in the header, opening a full‑screen drawer with the tree.
• Breadcrumb appears as a single line above the list, truncated with ellipsis if long.

3.4.2 File Cards/Table

Support both table and card view:

• Table view (default on desktop):
  • Columns: Name, Type, Size, Modified, Visibility.
• Card view (toggle):
  • Each card shows thumbnail/icon, name, size, and quick actions.

Search bar sits above the list, with placeholder: “Search files and folders”.

---

3.5 Stage 5 – Admin Panel and Moderation Tools

Goal: Allow admins to manage content and users efficiently, with clear risk indicators.

3.5.1 Admin Overview Dashboard

Layout:

• Metric cards at top:
  • Total files.
  • Total storage.
  • Uploads today.
  • Downloads today.
• Middle section:
  • Simple charts (sparkline or bar chart for uploads/downloads over last 7–30 days).
• Bottom:
  • Two tables side‑by‑side (or stacked on mobile):
    • “Recent uploads” (last N).
    • “Recent flags” (content flagged for TOS or abuse).

Use a neutral background and accent charts with the primary color, following patterns from popular file management dashboards.⁵

3.5.2 Files and Users Admin Tables

Files page:

• Filters panel:
  • Date range.
  • Status (Active, Expired, Flagged).
  • Owner type (Anonymous, Authenticated).
  • Size range (optional).
• Table columns:
  • ID / Short ID.
  • Name (or bucket label).
  • Owner.
  • Size.
  • Uploaded.
  • Flags.
  • Actions.
• Actions:
  • “View details” (opens side drawer with metadata, logs, and links).
  • “Delete”.
  • “Change expiration”.
  • “Flag / Clear flag”.

Users page:

• Columns:
  • Email.
  • Role.
  • Total storage used.
  • Last active.
  • Status (Active, Locked).
• Actions:
  • “View user files” (filters Files page by user).
  • “Lock/Unlock account”.
  • “Change role”.

Destructive actions use red buttons and confirmation dialogs summarizing the consequences.

---

3.6 Stage 6 – Embeds, Public Views, and SEO

Goal: Make shared links visually appealing and galleries easy to browse.

3.6.1 File Landing Pages

Layout:

• Center column:
  • Top:
    • Thumbnail or icon (image / video / generic).
    • File name.
    • Size.
  • Primary action row:
    • “Download” (primary button).
    • “Copy link” (secondary).
    • “Open in browser” (for compatible types).
  • Metadata panel:
    • Expires: YYYY-MM-DD.
    • Downloads: N.
    • Owner (optional).
• For file owners, additional inline controls:
  • “Extend expiration”.
  • “Disable link”.
  • “Set password” (if supported).

This aligns with expectations for simple, clean landing pages similar to what users see in Erugo and comparable services that highlight a large primary action.²

3.6.2 Public Galleries

Grid layout:

• Cards per file:
  • Thumbnail or icon.
  • Name (truncated with ellipsis).
  • Size.
  • Quick actions on hover/tap: “View”, “Download”.

Gallery header:

• Title: folder name.
• Description: optional text from owner.
• Filters and sort:
  • Type (All, Images, Videos, Documents).
  • Sort by (Newest, Oldest, Name, Size).

On mobile, cards stack and filters become a dropdown or horizontal scrollable chip row.

---

3.7 Stage 7 – ShareX, CLI, and Desktop Integration

Goal: Make configuration and use of integrations effortless.

3.7.1 Integrations / API Settings

Under Settings → Integrations/API:

Sections:

1. API Tokens:
   • Table:
     • Name.
     • Scope (read/write).
     • Created at.
     • Last used.
   • Buttons:
     • “Create new token” (opens dialog with name + scope).
     • “Revoke” per token.
2. ShareX:
   • Description: one short paragraph explaining what ShareX is and how it works.
   • Buttons:
     • “Download ShareX config (.sxcu)” for anonymous upload.
     • “Download ShareX config (.sxcu)” for authenticated upload.
   • Below: simple numbered instructions, mirroring how other ShareX servers guide users (“Open ShareX → Destinations → Custom uploader → Import .sxcu”).^{6 7}
3. CLI:
   • Code block showing example:

warpbox upload ./file.ext \
  --server https://warpbox.example \
  --token <your-token>

- “Copy command” button.

---

3.8 Stage 8 – Storage Backends, Scaling, and Background Workers

Goal: Make operational complexity understandable through clear UI.

3.8.1 Storage Management Screen

In Admin → Storage:

• List of backends:
  • Name.
  • Type (Local, S3, etc.).
  • Default (Yes/No).
  • Status indicator (green/orange/red).
• Actions:
  • “Add backend”.
  • Per backend: “Edit”, “Test connection”, “Set as default”.

Backend configuration form:

• Fields:
  • Type dropdown.
  • For S3: endpoint, bucket, region, access key, secret key, prefix.
  • For local: base path.
• Test button:
  • On click, shows inline result (“Connection successful”, “Bucket not found”).

This mirrors configuration UX found in Cloudreve and similar multi‑backend tools.^{8 9}

3.8.2 Background Jobs View

Admin → Jobs / Tasks:

• Cards summarizing:
  • Cleanup: last run time, status.
  • Thumbnails: queue length, last error.
  • Stats aggregation: last run.
• Table of recent job executions:
  • Time.
  • Task type.
  • Status.
  • Duration.
  • Error message (if any).

---

3.9 Stage 9 – Theming, i18n, and QoL Extras

Goal: Allow instances to adopt their own identity and refine UX.

3.9.1 Branding and Themes

Admin → Branding:

• Fields:
  • Logo upload (light/dark variants optional).
  • Favicon upload.
  • Primary color picker.
  • Secondary/Accent color picker.
• Live preview panel:
  • Shows sample header, button, and card using chosen colors.

Users often request dark mode and custom branding in self‑hosted tools; Zipline, Erugo, and Cloudreve promote dark themes and custom branding as key features.^{10 3 2}

3.9.2 Languages and Locale

Settings → Language:

• User‑level dropdown for language selection.
• Admin setting for default instance language.

All text strings in the UI should be sourced from translation files, allowing community contributions.

3.9.3 Quality‑of‑Life UI

• QR codes on file landing pages:
  • Small QR icon next to link.
  • Clicking opens overlay with QR code and “Download link” caption.
• Text paste mode:
  • On upload page, tabs: “Files” and “Text”.
  • “Text” tab shows large textarea and “Create paste” button.
  • Result: landing page with monospace view and copy buttons.
• Email notifications:
  • Per‑file toggle in file details: “Notify me on first download”.
  • Summary of notification status in file table (icon).

---

4. Interaction Patterns and States

4.1 Loading and Empty States

• Use skeleton loaders or subtle spinners for:
  • Initial dashboard.
  • Admin overview.
  • Large folder loads.
• Empty states:
  • Should include:
    • Short explanation of what the page will show.
    • A primary action (e.g., “Upload file”, “Create folder”).

4.2 Errors and Validation

• Local validation (like required fields) should be indicated:
  • Red border around field.
  • Short error text below.
• Server errors:
  • Show as banner at top of content area:
    • Example: “Unable to save changes. Please try again.”
• Critical destructive actions:
  • Use confirmation dialogs that:
    • Name the item.
    • Ask explicit confirmation (input of name optional for irreversible actions).

4.3 Notifications and Toasts

• Use small toast notifications for transient events:
  • Upload completed.
  • Link copied.
  • Settings saved.
• Behavior:
  • Appear in a consistent corner (e.g., bottom right).
  • Auto‑dismiss after a few seconds.
  • Pause dismissal when hovered.

---

5. Accessibility and Responsiveness

5.1 Accessibility

• Ensure all interactive elements:
  • Have accessible names (labels, aria‑labels).
  • Are reachable via keyboard.
• Modals:
  • Trap focus within the dialog.
  • Close on Esc.
• Screen readers:
  • Announce page titles on navigation.
  • Announce toast messages if they convey critical information.

5.2 Responsive Behavior

• Breakpoints:
  • Mobile: < 640px.
  • Tablet: 640–1024px.
  • Desktop: > 1024px.
• On smaller screens:
  • Sidebars collapse to menu buttons.
  • Tables may become stacked cards:
    • Each card shows the most important fields (name, size, key actions).

---

6. Consistency Rules

1. One primary action per view
   • Only one button per page uses the primary color and full button style.
   • All others are secondary or tertiary.
2. Shared components across modes
   • The upload component used for anonymous users is reused (with minor variations) for authenticated and admin contexts.
3. Uniform terminology
   • Use specific terms consistently:
     • “Upload”, not “Send”.
     • “Folder”, not “Directory”.
     • “File link”, not “URL” in user‑facing text.
4. Stable icon language
   • Use one icon set (line or filled) throughout.
   • Same icon always means the same action (trash for delete, pencil for edit).

---

This document is meant to be your comprehensive UI/UX specification. You can paste it directly into warpbox-ui-ux-style-guide.md in your repo and evolve it alongside your implementation stages.

⁂

---

1. https://www.reddit.com/r/selfhosted/comments/1oo826y/testing_cloudreve_as_a_lightweight_nextcloud/ ↩︎

2. https://erugo.app ↩︎

3. https://zipline.diced.sh ↩︎

4. https://www.reddit.com/r/selfhosted/comments/1cuubgj/best_way_to_share_a_file_privately_only_for_the/ ↩︎

5. https://forum.cloudron.io/topic/9624/cloudreve-self-hosted-file-management-and-sharing-system ↩︎

6. https://forum.cloudron.io/topic/10233/zipline-a-sharex-file-screenshot-upload-server-alternative-to-xbackbone ↩︎

7. https://noted.lol/zipline/ ↩︎

8. https://github.com/cloudreve/Cloudreve/blob/master/README.md ↩︎

9. https://github.com/loong64/Cloudreve ↩︎

10. https://github.com/ErugoOSS/Erugo ↩︎