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. Space Browsing (Explorer, Gallery, Documents, Recents)

  6. Folder Listing

  7. Add Pinned Folder / Folder Picker

  8. Transfer Destination Picker

  9. Broken Pin dialog

The navigation drawer belongs to the application shell and is not its own route.

Navigation Model

Compose Navigation routes:

  • section/home

  • section/trash

  • section/settings

  • section/about

  • home

  • settings

  • about

  • trash

  • space/{spaceId}

  • space/{spaceId}/folder/{uriEncoded}/{crumbsEncoded}

  • folder_picker/{uriEncoded}/{crumbsEncoded}

  • transfer_destination_picker

No bottom navigation. Home, Trash, Settings, and About are peer top-level graphs. The Home graph owns Home, Space browsing, Peek, and picker flows and retains that stack while another peer is selected.

Home, Trash, Settings, and About use a leading menu icon. Nested Space and picker destinations retain a back arrow. Space screens do not place a hamburger among their trailing content actions; a rightward drag beginning inside the screen opens the drawer without taking over Android’s extreme-edge Back gesture.

Home Screen

Layout

The Home dashboard contains application-wide Spaces, Recently Used, Recently Added, Pins, and Storage sections. Spaces, Pins, and Storage use compact two-column destination cards. Both recent-file sections use ordinary horizontal lists with a deliberate partial next-card peek and a See all action. At phone width, two complete cards remain visible with approximately 28 dp reserved for the next card; card width is bounded on smaller phones and tablets. Tapping a card opens it; horizontal movement browses recent cards while vertical movement continues to scroll Home. The earlier circular stacked deck is not part of the current interaction.

Recent cards use the same neutral surface treatment as the Recents Space grid, without tonal elevation. Both use a top artwork region followed by a bottom filename-and-metadata footer; Home presents the shared card in a horizontal list.

Recently Used is Treeger-owned opening history and can be cleared. Recently Added is a retained, limited Home projection of the newest eligible files in local shared storage. It queries MediaStore.Files directly, has no user-facing time-window claim, and cannot be cleared independently from the underlying files.

Source refreshes retain stable item identity and ordinary list position as far as possible. Every visible recent card is interactive and exposed to accessibility services.

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. Space icons use the same 20 dp size. Normal Pin cards do not show editing controls.

  1. Pins - user-managed cards. Common folders are seeded initially, remain fully editable/removable, and do not return after removal unless explicitly added again.

  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.

  • Search opens Device Storage in Explorer with search and filters expanded.

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

  • Tapping a pinned folder opens that folder.

  • Tapping Device Storage opens it directly.

  • Edit pins enters an explicit editing mode. Normal card metadata/icons are hidden to make room for one drag handle and one X unpin action per card.

  • Pressing and dragging a Pin’s handle in edit mode 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.

  • X removes the pin. Swipe-to-unpin is not supported.

Pin labels use the folder’s actual name; treeger does not assign alternate display names. The seeded download pin is therefore Download, and the camera pin targets the DCIM/Camera folder and is labeled Camera. Opening a nested pin restores its saved ancestor breadcrumbs so it has the same path context as manual browsing.

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."

Recents Space

Recents is a first-class Space with Used and Added tabs at the top. Home’s Recently Used and Recently Added See all actions open the corresponding tab. List is the default view; List/Grid, Grid density, and Sort preferences persist at the Recents Space level. Comfortable Grid uses three columns at phone width and Compact uses four. Search and the shared wrapping filters apply to the active tab. Clear history is available only for Used because Added reflects filesystem state. The app bar, tab row, and content canvas share background; the grid card uses the same neutral surfaceContainerHigh token as Home’s Recent cards.

Long press selects a visible Recent file in either List or Grid. Recents then uses the shared selection top bar and operation bar for Rename, Copy, Move, and Delete, with Share and Properties available from the top bar. Prepared Copy or Move items use the same Operation Shelf and Space-independent destination picker as Content Spaces. Used history follows saved-location migrations after rename, move, trash, and restore; Added refreshes its filesystem-derived results after direct mutations.

Add Pinned Folder Flow

  1. Tap New 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 device storage.

At Device Storage, the picker presents Pins followed by All folders. Both sections sort alphabetically, independent of Home pin order and the active Explorer Sort choice. Inside a folder, the picker lists its readable child folders alphabetically without repeating the root sections. A create-folder FAB remains available at every destination level and refreshes the list after successful creation. The Pins section is sourced directly from the complete persisted pin list; user-added pins are not silently removed by a second local-file availability filter. Each root section has an up/down chevron and its full heading toggles the section. The top app bar provides one expand-all/collapse-all action while both sections are available. The Add Pin folder picker follows the same section behavior. The picker 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.

Direct Drag Transfer Flow

Explorer List and Grid provide a direct path for destinations already visible in the folder hierarchy. After selection is active, long-pressing any selected item starts a drag for the complete selection. Eligible folder rows or cards use the secondary container while targeted. An enlarged drag preview stays well above the finger and shows the selected item name or count. Holding near the upper or lower browser edge continuously scrolls the folder contents while the drag remains active.

Holding over a folder for 1.2 seconds enters it without ending the drag. The user can repeat this through nested folders and release either directly on a visible folder or inside a folder entered by hover. Releasing opens one bottom sheet with the resolved destination, Copy here, Move here, and Cancel; individual folder rows never add persistent copy or move actions.

Ancestor breadcrumbs are also direct destinations. Breadcrumbs use enlarged touch targets during normal browsing and full-strip-height drop regions during a drag. Releasing on an ancestor resolves it as the destination; holding for 1.2 seconds enters it without ending the drag. Holding at the left or right breadcrumb edge scrolls long paths horizontally. Breadcrumb targeting takes priority over vertical folder edge scrolling while the pointer is inside the strip.

Cancel returns to the source with the original selection. Successful copy or move operations reuse the Operation Shelf and conflict flow, then select the successfully created top-level items in the destination. Skipped items are excluded. This result selection makes an accidental destination immediately correctable with another drag. Dropping a folder onto itself or one of its descendants, or onto an unavailable or read-only destination, is rejected.

Drawer

Drawer contents:

  • Home

  • Trash

  • Settings

  • About

The drawer also reflects the active theme through Material color tokens. It marks the current top-level graph, switches without stacking peer destinations, and preserves the active Home/Space stack while a peer destination is open.

Trash

Trash lists recoverable items with their deletion time and original location. Its 52 dp leading artwork uses the same thumbnail loader and neutral file fallback as Space list views. Image and video payloads retain their original filename and MIME identity for preview decoding even though Trash stores them under an internal payload path. Selection replaces the artwork with the standard primary check marker. The app bar exposes simple filename search with case-insensitive substring matching. Trash search does not expose Space scope, type, date, size, or source filters. A non-empty query with no results has a distinct no-matches state; Empty Trash always continues to apply to the full Trash collection rather than only visible matches. An end-to-start swipe on an unselected Trash row opens the existing Delete forever confirmation and does not remove the row before confirmation.

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. Their artwork and metadata share a rounded neutral surfaceContainerHigh card so supporting information does not float directly on the canvas. 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.

At the Explorer storage root, browse mode separates personalized Pins from the complete All folders section. Common folders are seeded as editable pins. Cards inside Pins do not repeat a pin marker. Matching cards in All folders use a primary tint and marker to communicate their pinned state. Download, Documents, DCIM/Camera, Pictures, Movies, Music, Android, and WhatsApp use semantic icons. Ordinary folders retain the neutral folder treatment.

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.

  • In List, an end-to-start swipe on an unselected, locally deletable item opens the existing Delete confirmation. The gesture is disabled during selection and while an Operation Shelf transfer is active.

View Modes And Space Preferences

View and Sort preferences are saved per Space, not per folder. This avoids forcing the same view across conceptually different Spaces without requiring repeated changes in every folder. Each Space definition supplies its default; Recents defaults to List.

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 show persisted direct-folder count, direct-file count, and recursive logical size from Treeger’s on-device catalogue. In List, folders use the same 48 dp neutral surfaceVariant artwork container as file thumbnails and file-type fallbacks; only the glyph changes by folder kind. Before the first summary is available, the reserved metadata line reads – folders · – files; persisted values remain visible during reconciliation. List and Grid share selection, properties, Search, Sort, and operation behavior. Sort remains consistent within the active Space.

Content and Recents grids expose Comfortable and Compact density in Browse options. At phone width, Comfortable uses three columns and Compact uses four; the choice persists per Space.

Gallery artwork metadata uses an opaque surface strip with onSurface text and onSurfaceVariant source artwork. The 24 dp strip separates metadata from uncontrolled thumbnail colors while remaining quieter than a high-contrast black scrim in light theme.

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.

Every visible section outside Home is expanded by default and its heading toggles between expanded and collapsed states with an up/down chevron. When a browser has multiple sections, its top app bar provides one expand-all/collapse-all action.

Successful rename, move, and Delete refreshes retain the current List or Grid viewport. If the anchored item was removed, the nearest surviving item remains at approximately the same screen position rather than returning the browser to the top.

The default scope searches the current folder. Scope can expand explicitly to subfolders or all device storage. Type, location, modified-date, size, and content-specific facets appear in a persistent wrapping filter section with no horizontal scrollbar. Recursive results show their source location and retain normal selection, properties, copy, move, share, and Delete behavior.

Search and Filters remain distinct controls: Search toggles the query field and filters together, while Filters toggles only the filter section. Active action icons use the active identity’s low-chroma primary container. Non-default filters use the same state treatment. 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.

Content Spaces additionally offer Source A-Z and Source Z-A. Selecting either sort automatically groups results under resolved sources such as Camera, Screenshots, Downloads, applications, or folders. Newest/date remains the default.

Long-press selection exposes contextual actions. Show in folder resolves the selected result’s immediate parent and opens it in Explorer with complete breadcrumbs.

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

Pins follow successful rename and move operations performed in treeger, including when an ancestor folder is moved. A pinned folder can become unreadable if it was deleted outside the normal Trash workflow or storage was disconnected.

On tap, if invalid:

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

  • Message: "It may have been 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

  • Surface variant #E5E8E9

  • Primary ink #182129

  • Secondary ink #5A646B

Dark foundation:

  • Canvas #10161C

  • Surface #141B22

  • Surface variant #2A343D

  • 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 #CD2C58 in light mode, with an accessible pale rose in dark mode

  • Rose as a restrained secondary accent

Home uses semantic extended containers: Spaces receive the supporting secondary-hue tint; Pins and Storage share the quieter folder-destination tint; recent cards remain neutral. Resting browser folders use surfaceContainerHigh. Selection always overrides the resting container with primaryContainer. Internal card dividers use outlineVariant.

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.

Breadcrumb ancestors use underlined primary text as the non-color click affordance. The current folder uses plain onSurface text and is not actionable. Overflowing paths initially keep the current folder visible and draw a subtle canvas-colored fade over whichever horizontal edge has additional breadcrumbs. The fade disappears at that boundary and never introduces a new theme color.

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.