08 — UI/UX Specification

From the Burrow™ specification set.

08 — UI/UX Specification

Design Goal

The interface is a storage management machine: precise, operational, and evidence-based. It is not a scare-tactic disk cleaner.

It should answer:

  1. How much storage am I using?
  2. What can I recover?
  3. Is important data protected?

Navigation

The public website homepage (/) is the product/info landing page. The website is documentation only (ADR-004). Retired console URLs (/dashboard, /storage, /files, /activity, /settings, and later mutation placeholders) redirect home. Dashboard, Storage, Files, Activity, and Settings below are Mac app views, not hosted routes.

  • Dashboard
  • Storage
  • Files
  • Duplicates
  • Cleanup
  • Archive
  • Backup
  • Activity
  • Settings

Unavailable future features may appear disabled or be hidden until implemented.

Dashboard

Storage Cards

For each configured volume/provider:

  • name;
  • role/provider;
  • used/free/capacity where meaningful;
  • locally allocated managed bytes;
  • last scan;
  • status.

0.1 binds a typed fixture payload (DashboardAnalyticsPayload) so hosted HTTPS can render cards without calling 127.0.0.1. Last scan and coverage are shown when a scan exists, and marked stale or absent when it does not. Cards may link to /storage?root=; the Storage drill-down page is a separate story. VLT-32 may replace fixture numbers with catalog queries without changing these fields.

Potential Recovery

Break down conservatively:

  • exact duplicates;
  • archive candidates;
  • Downloads;
  • installers/disk images;
  • large/stale files;
  • cloud files eligible for local eviction (future, separate from deletion).

Never present speculative categories as "safe to delete."

In 0.1 the dashboard shows large/stale allocated bytes only. Duplicate recovery is labeled not available in 0.1 and ships in 0.2. No dashboard control deletes, moves, archives, or backs up files.

Protection

Show collections with health:

  • Verified
  • Backed Up
  • Synced Only
  • At Risk
  • Stale
  • Destination Offline

Storage View

Drill into a volume/root with:

  • capacity;
  • scan coverage;
  • largest folders;
  • file-type distribution;
  • age distribution;
  • cloud state;
  • configured role.

Engine data for this view is Catalog.storageAnalytics() (VLT-32). It is catalog-read, includes scan timestamp/age, distinguishes cloud vs local allocation (allocated_size_bytes for reclaim), and does not attach a "safe to delete" recommendation. Duplicate recovery waits for 0.2. Dashboard cards (VLT-34) and drill-down (VLT-36) consume that report.

Release 0.1 binds this view to per-root fixture payloads at /storage, /storage/{rootId}, and /storage?root=. Incomplete coverage is shown as a warning. The view is read-only: it has no delete, move, archive, or backup controls. The payload type is additive so catalog analytics can replace fixture numbers later. Hosted HTTPS cannot call 127.0.0.1.

Files View

Table fields:

  • name;
  • path;
  • size;
  • allocated size;
  • modified;
  • location/provider;
  • cloud state;
  • protection;
  • recommendation.

Filters should be first-class.

Release 0.1 binds this view to a typed fixture catalog query (queryFiles) at /files. Search matches name or path. Filters are location, type, size, age, and cloud state as data exists. The query is catalog-read and rejects a root or path prefix that is not already approved — it does not scan a new unapproved path. Hosted HTTPS cannot call 127.0.0.1; fixture rows are the public-site source. Hash and duplicate columns wait for 0.2. The table is read-only: no delete, move, archive, or backup row actions. A later catalog bind can set source: "catalog" without changing field names.

Duplicates View

Group-centric presentation.

Each group shows:

  • confidence/type;
  • hash status;
  • group size;
  • number of copies;
  • reclaimable local bytes.

Expanding a group shows every copy and relevant protection context.

Recommendation Explanation

Every recommendation must have a "Why?" explanation with deterministic evidence.

Example:

Archive candidate because this 8.4 GB project has not changed in 327 days. No automatic action will be taken.

Scan Experience

User chooses roots, sees exclusions, starts scan, and can cancel.

Progress must show useful activity without implying precision when total work is unknown.

Activity

The Activity view is a read-only operational log for scan start, finish, cancel, and errors.

  • Completing or cancelling a fixture scan creates scan-started plus scan-completed or scan-cancelled rows.
  • Errors from a partial scan appear in the same list.
  • 0.1 mutation rows are denied SafetyGate attempts only. Do not show successful delete, move, archive, or backup events.
  • The view must not start a scan, run cleanup, or otherwise mutate files.
  • Hosted HTTPS cannot reach BurrowEngine on 127.0.0.1. The public site shows fixture/in-memory events. Persist stays on ActivityService until a catalog activity table exists.

Safety UX

Future mutation actions require a review screen summarizing:

  • exact files;
  • source/destination;
  • cloud impact;
  • backup/verification;
  • bytes affected;
  • reversible vs permanent action.

Accessibility

Use semantic controls, keyboard navigation, sufficient contrast, non-color-only status indicators, and readable tables.

Visual Direction

Professional Platypus Software utility: compact, information-dense, restrained. Avoid gimmicky cleaner-app animations and aggressive "YOU HAVE 847 GB OF JUNK!" messaging.