Skip to content
sysout.dev

Treeger - UI Screens, Navigation, UX Behaviour

Screen inventory, navigation, interaction behavior, visual states, and accessibility expectations for Treeger.

Package: dev.sysout.treeger

Scope basis: the original design document describes the original MVP baseline. Later roadmap deliveries now add standard file operations, Trash, and scoped search while preserving the same navigation and neutral visual system.

Screen Inventory

  1. Home

  2. Settings

  3. About

  4. Trash

  5. Folder Listing

  6. Add Pinned Folder / Folder Picker

  7. Transfer Destination Picker

  8. Broken Pin dialog

The navigation drawer is an overlay on Home, not its own route.

Navigation Model

Compose Navigation routes:

  • home

  • settings

  • about

  • trash

  • folder/{uriEncoded}/{crumbsEncoded}

  • folder_picker/{uriEncoded}/{crumbsEncoded}

  • transfer_destination_picker

No bottom navigation. Home is the root destination; folder browsing is a drill-in flow, and Trash/Settings/About live in the drawer.

Home uses a leading menu icon. Folder Listing and Folder Picker use a back arrow in the same position because they are not root screens.

Home Screen

Layout

The Home dashboard contains application-wide Spaces, Recently Used, Pins, and Storage sections. Spaces, Pins, and Storage use compact two-column destination cards; Recently Used remains a full-width list so filenames and file metadata retain enough horizontal space.

All destination cards share the same subtle surface treatment. Folder destinations use a bare 20 dp folder icon rather than nesting a second icon surface inside the card. Space and Storage labels use a larger semibold single-line style; Pin labels use the more compact semibold body style to leave room for the reorder control. Space icons use the same 20 dp size. The Pin reorder affordance keeps a comfortable touch target while drawing a low-contrast 20 dp four-direction icon.

  1. Pins - user-managed cards. Each card has a folder icon, display name, and a trailing four-direction reorder handle.

  2. Storage - fixed destination cards, initially Device Storage.

Storage is available when all-files access is granted and does not need pinning.

Actions

  • Menu in the top app bar opens the drawer.

  • + beside the Pins header opens the in-app folder picker.

  • Tapping a pinned folder opens that folder.

  • Tapping Device Storage opens it directly.

  • Pressing and dragging a Pin’s handle reorders it across both grid axes. The dragged card follows the pointer while displaced cards animate into position; the resulting order is persisted when the drag ends.

  • Swiping a Pin card left removes the pin and offers Undo.

If all-files access is not granted, Storage shows a short permission row with an action to open Android’s all-files access settings for treeger.

Empty States

  • Empty pinned list: "Nothing pinned yet - tap + to add a folder."

  • Unavailable storage: "Device Storage is not available."

Add Pinned Folder Flow

  1. Tap + beside Pins.

  2. If all-files access is missing, open the system all-files access settings.

  3. If access is present, open treeger’s in-app folder picker.

  4. User selects the current folder with the explicit Pin folder button immediately below the breadcrumbs and before any child-folder rows.

  5. New pin is appended to the pinned list and persisted to DataStore.

The folder picker starts from external storage and lets the user drill down through local folders. It does not use the system SAF picker in the current MVP.

Transfer Destination Flow

When Copy or Move is prepared from a Content Space, the Operation Shelf has no current folder and presents a prominent Browse action. Browse opens a dedicated, Space-independent destination picker rooted at internal storage.

The picker lists readable child folders and retains an in-screen folder history. Breadcrumbs jump to an ancestor; Back moves to the previous folder and exits after the root. The same Operation Shelf remains visible. Before a destination is chosen, its first row shows Selected in one summary cell and a single primary Browse button in the other; empty Destination or Not selected labels are not shown. Once chosen, Selected and Destination become equal summary columns and Browse is attached to Destination. The second row distributes intrinsic-width Copy here or Move here, Review items, and Cancel buttons like grid items rather than stretching them; Review and Cancel are outlined. The selected-item count appears only in the summary. An invalid destination disables the action and explains why. Starting the operation returns to the originating Space, where normal progress, conflict, completion, and failure states continue.

Hierarchical browsing also injects Browse while retaining its current folder as the immediate destination. This capability boundary is based on the browser entry point, never on Explorer, Gallery, or Documents Space IDs.

Drawer

Drawer contents:

  • Home

  • Trash

  • Settings

  • About

The drawer also reflects the active theme through Material color tokens.

Settings

Settings contains the Canopy/Bloom identity choice and file browsing preferences, including hidden files and Trash retention. Light/dark mode follows Android’s system setting.

About

About identifies treeger, explains its file-manager and gallery scope, shows the current build version, and presents external legal links with browser guidance.

Folder Listing Screen

Layout

  • Top app bar: current folder name

  • Breadcrumb row beneath the app bar, using larger semibold labels

  • Search and a single overflow action; overflow directly opens Browse options

  • Folder/file content: folders first, files second, in List or Grid

List rows show a compact thumbnail or fallback artwork, name, and one supporting line. In Grid, folders use neutral compact horizontal cards, two per row, with a bare 20 dp folder icon and semibold name. Files remain three-per-row artwork tiles with up to two filename lines and one supporting line. Ordinary files use size as the supporting value; folders do not repeat a Folder label. Recursive search results use their location when that context is more useful than size.

Actions

  • Tap folder row: push a new Folder Listing route for that folder.

  • Tap file row: hand off to another app using ACTION_VIEW.

  • Search remains directly available in the top app bar.

  • Overflow directly opens one modal Browse options sheet rather than a nested menu.

  • Browse options presents Space, View, and Sort choices as labeled chips. The active values use the selected-chip treatment and changes apply immediately.

  • Entry-point actions are capability based: hierarchical browsing supplies Pin folder or Unpin folder, while content browsing supplies Refresh.

View Modes And Folder Memory

DCIM, Pictures, and their local descendants default to Grid. Every other folder defaults to List. Choosing the other mode creates an override for that exact folder; Use default removes it. View-mode overrides follow renamed and moved folders.

Grid uses six virtual columns at the reference phone width: folder cards span three columns and file artwork spans two. Images use bounded, memory-cached thumbnails; other files use low-chroma extension tiles. Folder cards intentionally omit size, creation time, and direct-child count because the current file-provider abstractions cannot supply those values reliably without additional traversal. List and Grid share selection, properties, Search, Sort, and operation behavior. Sort remains global in this delivery.

Search And Sort

Search opens beneath the existing breadcrumbs. Sort applies to both ordinary folder contents and search results and is selected from chips in the Browse options sheet; there is no second dropdown layer or persistent sort label in the content area.

Sort also determines the visible sections in both List and Grid. Date uses Today, Yesterday, and individual days; Name uses locale-aware initial letters plus #; Type uses friendly file types; Size uses stable size ranges. Sort direction sets section order. Folders remain in one leading section because their size and modified metadata are not reliable grouping signals. Users without a stored Sort start with Newest; an existing stored choice is preserved.

The default scope searches the current folder. Scope can expand explicitly to subfolders or all internal storage. Type, modified-date, and size filters appear as a horizontally scrollable chip row. Recursive results show their source location and retain normal selection, properties, copy, move, share, and Delete behavior.

Non-default filters use the active identity’s low-chroma primary container. Search result summaries use semibold primary ink; partial-search and unavailable-folder details remain in secondary ink.

Content Spaces derive a temporary Format menu from the formats actually present in their retained result snapshot. Available PDF, Plain text, HTML, Markdown, Rich text, Word, Spreadsheet, Presentation, Ebook, AsciiDoc, JSON, and XML entries show result counts. Unknown text formats remain under All formats rather than being grouped into Plain text. The selection is retained with the Space session and combines with query, broad type, location, modified-date, and size filters. This is a generic Content-browser facet and does not depend on a Documents Space ID.

Recursive search is incremental, cancellable, and local. It does not require or create a permanent content index.

If no app can open a file, show a Snackbar: "No app found to open this file."

When handing AsciiDoc files to Android, .adoc, .asciidoc, and .asc use text/plain. This avoids the unrelated and duplicated handlers produced by a / fallback while remaining compatible with editors that accept ordinary text files.

Broken Pin Handling

A pinned folder can become unreadable if it was moved, deleted, or storage was disconnected.

On tap, if invalid:

  • Dialog title: "This folder can’t be found"

  • Message: "It may have been moved, deleted, or storage was disconnected."

  • Actions: Remove pin / Cancel

The app checks lazily on tap rather than scanning every pin on every launch.

Theming

The app uses a neutral light/dark foundation with selectable Canopy and Bloom identity colors. Both identities share the exact foundation and semantic tokens.

Light foundation:

  • Canvas #F8F7F3

  • Surface #FCFCFA

  • Primary ink #182129

Dark foundation:

  • Canvas #10161C

  • Surface #172029

  • Primary ink #F2F1EC

Canopy identity:

  • Navy #0A2947 in light mode, with a lighter accessible blue in dark mode

  • Ochre #8B5E3C as a restrained secondary accent

Bloom identity:

  • Berry #B72550 in light mode, with an accessible pale rose in dark mode

  • Rose as a restrained secondary accent

Permanent title bars, breadcrumbs, section headings, and ordinary list rows use the canvas together. A heading such as Recently Used and the files belonging to it must not form separate color bands. Surface colors remain available for contained modules and temporary overlays.

Error colors are semantic and remain separate from both identity packs.

OS-owned surfaces such as Android Settings and external file viewers are not themed by treeger.

Startup UX

The native launch theme is aligned with Canopy light/dark. Compose renders a quiet startup surface until persisted theme/pins/sort values are loaded, reducing visible phase changes between splash, system bars, app chrome, and home content.