[Design audit] Improve contrast, compact player hierarchy and recovery clarity #47

Open
opened 2026-09-18 11:20:34 +02:00 by alexander · 3 comments
Owner

Purpose

Improve BookWave's readability, compact-player hierarchy and recovery clarity while preserving its native Compose/Material 3 design and cover-led visual direction.

Hallmark source-based audit of main at 8f0ff5926687b3373703ee972dbb1392a0792d63, 2026-09-18. Rendered layouts, TalkBack and physical-device performance were not verified. Primary ownership: UI & Experience. This feedback feeds the canonical roadmap; it does not supersede playback-correctness sequencing.

  1. Critical — guarantee accent contrast. Theme.kt:219–237 selects white until background luminance exceeds 0.5. At luminance 0.30 white is only 3:1. Compare actual foreground contrast ratios and choose the stronger pair; validate onPrimary/onPrimaryContainer and text-contrast settings on effective backgrounds. This proves a helper weakness, not which shipped presets fail.
  2. Major — simplify compact mini-player hierarchy. MiniPlayer.kt:254–313 reserves five 48 dp buttons plus 46 dp artwork; at 320 dp approximately 18 dp remains for text after padding. Add an adaptive compact arrangement that retains play/pause and useful skips, moving sleep/stop into expanded or accessible secondary controls. Preserve the current minimum height and 48 dp targets.
  3. Major — truthful download recovery actions. DownloadsScreen.kt:317–349 can show Pause on failed, unpaused rows. Use Pause/Resume/Retry according to state and distinguish waiting/automatic retry from terminal failure. Track implementation in existing #18, #19 and #29; do not duplicate these work items.
  4. Major — connection status beyond color. HomeScreen.kt:1331–1365 uses one dot shape; contentDescription does not resolve ambiguity for sighted color-blind users. Add distinguishable symbols and accessible detail; resolve semantic status colors against the active app appearance instead of isSystemInDarkTheme().
  5. Major — distinguish whole-book and chapter seek. FullPlayer.kt:482–573 labels the chapter slider for accessibility but leaves the whole-book slider unnamed. Add Book position/Chapter position labels and meaningful elapsed/remaining spoken values; preserve thin tracks and full targets.
  6. Minor — restrain routine motion. MiniPlayer.kt:108–116 uses MediumBouncy entrance. Prefer a short non-bouncy transition, verify reduced motion and make complete titles available without requiring endless marquee animation.
  7. Minor — actionable no-results state. HomeScreen.kt:1257–1265 has no recovery CTA. Add Clear search/Reset filters according to the active constraint without clearing the chosen library.

Acceptance

  • Validate compact/expanded windows, 320/375/414/768 dp widths, portrait/landscape and font scaling through 2.0.
  • Cover light, dark, AMOLED, dynamic color and background packs.
  • Verify loading, offline, failed, empty and active-playback states, TalkBack and reduced motion.
  • Test contrast pairs numerically; verify accessible labels and target sizes with appropriate UI tests.
  • Record device evidence separately from source/JVM evidence.
  • Keep native typography, intentional centered player artwork and optional AMOLED; no wholesale rebrand or navigation rebuild.

Audit count: 1 critical · 4 major · 2 minor.

## Purpose Improve BookWave's readability, compact-player hierarchy and recovery clarity while preserving its native Compose/Material 3 design and cover-led visual direction. Hallmark source-based audit of main at `8f0ff5926687b3373703ee972dbb1392a0792d63`, 2026-09-18. Rendered layouts, TalkBack and physical-device performance were not verified. Primary ownership: UI & Experience. This feedback feeds the canonical roadmap; it does not supersede playback-correctness sequencing. ## Findings and recommended changes 1. **Critical — guarantee accent contrast.** [Theme.kt:219–237](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/core/designsystem/src/main/kotlin/com/example/shelfplayer/core/designsystem/theme/Theme.kt#L219) selects white until background luminance exceeds 0.5. At luminance 0.30 white is only 3:1. Compare actual foreground contrast ratios and choose the stronger pair; validate onPrimary/onPrimaryContainer and text-contrast settings on effective backgrounds. This proves a helper weakness, not which shipped presets fail. 2. **Major — simplify compact mini-player hierarchy.** [MiniPlayer.kt:254–313](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/player/MiniPlayer.kt#L254) reserves five 48 dp buttons plus 46 dp artwork; at 320 dp approximately 18 dp remains for text after padding. Add an adaptive compact arrangement that retains play/pause and useful skips, moving sleep/stop into expanded or accessible secondary controls. Preserve the current minimum height and 48 dp targets. 3. **Major — truthful download recovery actions.** [DownloadsScreen.kt:317–349](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/downloads/DownloadsScreen.kt#L317) can show Pause on failed, unpaused rows. Use Pause/Resume/Retry according to state and distinguish waiting/automatic retry from terminal failure. **Track implementation in existing #18, #19 and #29; do not duplicate these work items.** 4. **Major — connection status beyond color.** [HomeScreen.kt:1331–1365](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/home/HomeScreen.kt#L1331) uses one dot shape; contentDescription does not resolve ambiguity for sighted color-blind users. Add distinguishable symbols and accessible detail; resolve semantic status colors against the active app appearance instead of isSystemInDarkTheme(). 5. **Major — distinguish whole-book and chapter seek.** [FullPlayer.kt:482–573](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/player/FullPlayer.kt#L482) labels the chapter slider for accessibility but leaves the whole-book slider unnamed. Add Book position/Chapter position labels and meaningful elapsed/remaining spoken values; preserve thin tracks and full targets. 6. **Minor — restrain routine motion.** [MiniPlayer.kt:108–116](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/player/MiniPlayer.kt#L108) uses MediumBouncy entrance. Prefer a short non-bouncy transition, verify reduced motion and make complete titles available without requiring endless marquee animation. 7. **Minor — actionable no-results state.** [HomeScreen.kt:1257–1265](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/home/HomeScreen.kt#L1257) has no recovery CTA. Add Clear search/Reset filters according to the active constraint without clearing the chosen library. ## Acceptance - Validate compact/expanded windows, 320/375/414/768 dp widths, portrait/landscape and font scaling through 2.0. - Cover light, dark, AMOLED, dynamic color and background packs. - Verify loading, offline, failed, empty and active-playback states, TalkBack and reduced motion. - Test contrast pairs numerically; verify accessible labels and target sizes with appropriate UI tests. - Record device evidence separately from source/JVM evidence. - Keep native typography, intentional centered player artwork and optional AMOLED; no wholesale rebrand or navigation rebuild. Audit count: **1 critical · 4 major · 2 minor**.
Author
Owner

BookWave: Home, profile picker and Appearance design review

Reviewed 18 September 2026 against main at 8f0ff5926687b3373703ee972dbb1392a0792d63.

Scope and evidence

This second Hallmark audit covers Home shelf cards; Books, Series, Authors and Genres tabs; the flat book list; profile picker; and Settings → Appearance. Other Settings tab contents are excluded because they have not yet been improved.

All implementation evidence was read from Forgejo through prox2-mcp-gateway. The original GitHub repository was used only to locate filenames because the gateway exposes no tree-listing tool. No application files were changed. This is a source-based review, not a rendered-device acceptance pass. Layout risks below need reproduction at the stated sizes; aesthetic recommendations are identified as recommendations rather than observed rendering failures.

The first audit is tracked in issue #47. Its contrast and mini-player findings remain relevant and are not counted again here.

Design direction to preserve

Keep BookWave cover-led and native. Home shelves support recognition and resumption; the flat list supports scanning and finding; collection tabs organize the library; the profile picker should prioritize account identity and switching; Appearance should show the effect of a choice before requiring the user to interpret settings terminology.

Good existing decisions:

  • Author portraits have cached-cover fallbacks; series use stacks and genres use mosaics. These are meaningful differences, not decorative variation.
  • Empty Home shelves disappear, and play/resume has its own labelled control alongside the details action.
  • Series/group cards already use minimum heights rather than fixed heights.
  • The profile picker has an active badge, server identity, passcode information and reauthentication copy.
  • Appearance has coherent Theme → Colour → Glass → Language groups, inline disclosure, 48 dp swatch cells and a named wallpaper-color option.

Keep the established author-before-title shelf order and compact player preferences unless deliberately reconsidered. No wholesale rebrand, replacement navigation system or removal of glass is proposed.

Major findings

1. Flat list: fixed row height conflicts with scalable content

Hallmark lens: responsive layout and typography. feature/browse/BookListUi.kt:83; row height is 132 dp at line 195.

A row must accommodate a two-line title, author, optional series, progress copy, progress bar and 32 dp vertical padding. The series and progress text can wrap, while the outer height cannot grow. This creates a strong clipping/compression risk at larger font scales and with long metadata.

Change: use a minimum height and content-driven expansion. Decouple the cover from full row height so increasing text size does not enlarge the cover and further reduce text width. Preserve equal baseline density at default size.

Acceptance: long title + long series + progress visible at 320/360 dp and 2.0 font scale; no missing lines or overlapping controls. This needs a rendered test, not a source-only pass.

2. Profile picker: the last actions can sit behind the mini-player

Hallmark lens: overlay/layout safety. feature/profiles/ProfileSwitcherScreen.kt:126 and MainActivity.kt:277.

The profile list has only 16 dp content padding. The application draws the mini-player over the navigation graph, and this screen does not consume the player clearance used elsewhere. With enough profiles to fill the screen, the last card or Add profile action can remain under that overlay.

Change: add measured player clearance to the list's bottom content padding. Use a bounded readable width on tablets while touching this layout.

Acceptance: with a loaded book and a long profile list, scroll every final action fully above the player at normal and large text sizes.

3. Appearance: preview colors can disagree with the selected background pack

Hallmark lens: design-system consistency. feature/settings/SettingsScreen.kt:404, MainActivity.kt:112, feature/settings/AppearanceTab.kt:177.

The activity resolves darkness from the selected background pack first. Settings instead supplies appearance.theme.isDark ?: systemIsDark to Appearance. Accent swatches and wallpaper preview then use that value. A dark pack over a light base/system setting can therefore preview the light variant while the app renders the dark one, or vice versa.

Change: use the same resolved appearance value for the application and all preview controls. Keep that resolution in the existing appearance ownership boundary.

Acceptance: dark pack + light system, light pack + dark system, explicit accent and wallpaper accent all show the color actually applied.

4. Home cards: several perpetual marquees compete for attention

Hallmark lens: unnecessary continuous motion. feature/home/HomeShelvesUi.kt:297 and feature/home/HomeShelvesUi.kt:381.

Author, title and series each use an infinite marquee on 160 dp cards. Several visible cards can animate several lines simultaneously, especially at large font sizes. This makes a recognition surface harder to scan.

Change: preserve full-title access while reducing simultaneous movement: allow a larger card/text layout at large font sizes, or animate only the explicitly focused/selected card. Provide a static reduced-motion treatment and keep complete metadata available in details and accessibility text. Treat two-line titles as an option to evaluate, not an automatic reversal of the prior compact-card preference.

Acceptance: a shelf of long metadata remains readable without watching multiple moving lines; reduced motion does not hide the full title.

5. Home cards: progress readings lack explicit meaning and room to grow

Hallmark lens: hierarchy, accessibility and responsive text. feature/home/HomeShelvesUi.kt:340.

Elapsed time, percentage and remaining time share one unweighted row in roughly 136 dp of inner width. They are bare values, and the source explicitly acknowledges that their spoken meaning depends on order. Long durations and larger fonts have little room.

Change: prioritize “time left” visually, or retain all three in an adaptive two-row treatment. Provide a complete card announcement that includes book identity and labels each reading; avoid a child contentDescription that replaces the book title. Keep Play as a separate accessible action.

Acceptance: long-duration values remain intact at 2.0 font scale; TalkBack identifies the book, elapsed and remaining time, and the distinct play action.

6. Collection tabs: artwork uses too much of narrow cards

Hallmark lens: hierarchy and responsive allocation. feature/browse/SeriesListUi.kt:58 and feature/browse/SeriesListUi.kt:115.

Series artwork reserves 140 dp; author/genre artwork reserves 132 dp. At 320 dp with Home's outer margins and the text padding, only about 116–124 dp remains for text before a genre Edit button is added. Cards can grow vertically, but the fixed artwork makes long names unnecessarily narrow.

Change: keep the stack/portrait/mosaic identities, but use smaller bounded artwork on narrow windows or a compact alternate layout at large font sizes. Keep the genre edit action separate from the browse target; move it to a secondary row/menu when width is insufficient.

Acceptance: long series, author and genre names are readable without tall, narrow text columns; edit remains independently reachable.

7. Profile picker: switching and account maintenance have equal emphasis

Hallmark lens: action hierarchy and interaction states. feature/profiles/ProfileSwitcherScreen.kt:211 and feature/profiles/ProfileSwitcherScreen.kt:287.

Inactive cards are tappable and also contain Use, Sign out/Sign in again, and Remove in one row. Routine switching and destructive maintenance occupy the same visual tier. Busy state disables actions but does not show which profile is being switched.

Change: make the profile identity/switch region the primary action, with a separate account menu for sign-out/removal. Keep reauthentication visible when needed and preserve the removal explanation. Display username alongside server when it differs from the display name. Add a targeted “Switching…” state and selected-state semantics; do not introduce another owner for switching policy.

Acceptance: users can identify the active account, choose the correct same-name account on another server, and distinguish switching from removal at large text sizes.

8. Appearance: color choices hide useful identity and close too quickly

Hallmark lens: discoverability and state clarity. feature/settings/AppearanceTab.kt:378 and feature/settings/AppearanceTab.kt:555.

The collapsed color row shows a swatch but not the current color's visible name. Expanded swatches are named only for accessibility, selection uses a stronger ring, and each choice closes the palette. Comparing nearby colors requires repeatedly reopening it. “Follow accent” is a behavioral choice presented largely as another color.

Change: show the selected name/source alongside the swatch, give the selected option a clear checkmark, and keep the palette open during comparison. Present Follow accent as a named source option, like the existing wallpaper option, rather than relying on its resolved hue. Preserve the 48 dp targets.

Acceptance: the chosen color and its source are understandable without distinguishing subtle hues; comparison takes one open interaction.

Minor findings and design refinements

9. Appearance: previews show backgrounds, not the resulting interface

Hallmark lens: specificity and useful feedback. feature/settings/AppearanceTab.kt:95 and feature/settings/AppearanceTab.kt:213.

Theme thumbnails show artwork or flat grounds, while glass controls expose blur values and separate card/system tint switches. They do not demonstrate their combined effect on readable text and controls.

Change: add one small live preview using real shared card/control components, without a fake phone frame. Explain Card tint and Navigation/player tint in user terms; offer an explicit restore-defaults action. Show a platform explanation when blur is unavailable and verify the fallback rather than promising the same glass on every Android version.

10. Home tabs: adapt to available width, not only font scale

Hallmark lens: responsive navigation. feature/home/HomeScreen.kt:739 and feature/home/HomeScreen.kt:861.

The horizontal-to-stacked change depends only on a 1.3 font-scale threshold. Window width and translated label length can cause crowding before that threshold.

Change: choose the arrangement using available width and label fit as well as font scale. Preserve readable labels and tap targets; allow platform-appropriate wrapping when required for accessibility rather than forcing a web-style one-line rule. Validate all four tabs with the mini-player present.

11. Flat list: filter and sort have the same chip treatment

Hallmark lens: hierarchy and restraint. feature/home/HomeScreen.kt:1070 and feature/browse/BookListUi.kt:202.

Search, focused collection, filter chips and seven sort choices can accumulate in the pinned header. Filters change membership; sorting changes order, but they look like parallel categories.

Change: retain the useful All / Continue / Downloaded filters and consider one labelled “Sort: Last played” control that opens the order choices. Show active collection scope clearly. Validate this as a density improvement rather than hiding the way out of an empty result.

12. Card artwork: failed URLs have a weaker fallback than absent URLs

Hallmark lens: complete image states. feature/browse/BookCover.kt:45.

A missing URL draws the book glyph. A non-null URL uses AsyncImage without an explicit loading/error placeholder; failed requests retain the background box but lose the clear fallback symbol. Author imagery already has a more complete fallback treatment.

Change: use the same stable cover placeholder for loading, missing and failed imagery, optionally distinguishing an actionable failure only where useful. Do not change card geometry when loading finishes.

  1. Correct fixed-height rows, profile overlay clearance and appearance preview resolution.
  2. Improve shelf progress readability, collection width allocation and profile action hierarchy.
  3. Refine palette comparison, previews, tabs, filters and image states.

Keep the canonical roadmap authoritative. This review is a candidate UI backlog, not permission to pull visual work ahead of active playback correctness.

Verify on Android at 320/375/414/768 dp widths and larger tablet windows, font scales 1.0/1.3/2.0, portrait/landscape, long English/Norwegian labels, light/dark/AMOLED/background packs, and reduced motion. Include offline/missing covers, long metadata, signed-out and locked profiles, and active playback. Test TalkBack order, selection, expanded/collapsed state, separate nested actions and touch targets. Verify actual glass/background contrast and pre-Android-12 fallback separately.

Verdict: preserve the visual identity and meaningful card families; improve adaptive geometry and make actions and appearance choices easier to understand.

0 new critical · 8 major · 4 minor.

<!-- Hallmark · pre-emit critique: P5 H5 E4 S5 R5 V4 --> # BookWave: Home, profile picker and Appearance design review Reviewed 18 September 2026 against main at `8f0ff5926687b3373703ee972dbb1392a0792d63`. ## Scope and evidence This second Hallmark audit covers Home shelf cards; Books, Series, Authors and Genres tabs; the flat book list; profile picker; and Settings → Appearance. Other Settings tab contents are excluded because they have not yet been improved. All implementation evidence was read from Forgejo through prox2-mcp-gateway. The original GitHub repository was used only to locate filenames because the gateway exposes no tree-listing tool. No application files were changed. This is a source-based review, not a rendered-device acceptance pass. Layout risks below need reproduction at the stated sizes; aesthetic recommendations are identified as recommendations rather than observed rendering failures. The first audit is tracked in [issue #47](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/issues/47). Its contrast and mini-player findings remain relevant and are not counted again here. ## Design direction to preserve Keep BookWave cover-led and native. Home shelves support recognition and resumption; the flat list supports scanning and finding; collection tabs organize the library; the profile picker should prioritize account identity and switching; Appearance should show the effect of a choice before requiring the user to interpret settings terminology. Good existing decisions: - Author portraits have cached-cover fallbacks; series use stacks and genres use mosaics. These are meaningful differences, not decorative variation. - Empty Home shelves disappear, and play/resume has its own labelled control alongside the details action. - Series/group cards already use minimum heights rather than fixed heights. - The profile picker has an active badge, server identity, passcode information and reauthentication copy. - Appearance has coherent Theme → Colour → Glass → Language groups, inline disclosure, 48 dp swatch cells and a named wallpaper-color option. Keep the established author-before-title shelf order and compact player preferences unless deliberately reconsidered. No wholesale rebrand, replacement navigation system or removal of glass is proposed. ## Major findings ### 1. Flat list: fixed row height conflicts with scalable content **Hallmark lens: responsive layout and typography.** [feature/browse/BookListUi.kt:83](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/browse/BookListUi.kt#L83); row height is 132 dp at line 195. A row must accommodate a two-line title, author, optional series, progress copy, progress bar and 32 dp vertical padding. The series and progress text can wrap, while the outer height cannot grow. This creates a strong clipping/compression risk at larger font scales and with long metadata. **Change:** use a minimum height and content-driven expansion. Decouple the cover from full row height so increasing text size does not enlarge the cover and further reduce text width. Preserve equal baseline density at default size. **Acceptance:** long title + long series + progress visible at 320/360 dp and 2.0 font scale; no missing lines or overlapping controls. This needs a rendered test, not a source-only pass. ### 2. Profile picker: the last actions can sit behind the mini-player **Hallmark lens: overlay/layout safety.** [feature/profiles/ProfileSwitcherScreen.kt:126](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/profiles/ProfileSwitcherScreen.kt#L126) and [MainActivity.kt:277](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/MainActivity.kt#L277). The profile list has only 16 dp content padding. The application draws the mini-player over the navigation graph, and this screen does not consume the player clearance used elsewhere. With enough profiles to fill the screen, the last card or Add profile action can remain under that overlay. **Change:** add measured player clearance to the list's bottom content padding. Use a bounded readable width on tablets while touching this layout. **Acceptance:** with a loaded book and a long profile list, scroll every final action fully above the player at normal and large text sizes. ### 3. Appearance: preview colors can disagree with the selected background pack **Hallmark lens: design-system consistency.** [feature/settings/SettingsScreen.kt:404](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/settings/SettingsScreen.kt#L404), [MainActivity.kt:112](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/MainActivity.kt#L112), [feature/settings/AppearanceTab.kt:177](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/settings/AppearanceTab.kt#L177). The activity resolves darkness from the selected background pack first. Settings instead supplies `appearance.theme.isDark ?: systemIsDark` to Appearance. Accent swatches and wallpaper preview then use that value. A dark pack over a light base/system setting can therefore preview the light variant while the app renders the dark one, or vice versa. **Change:** use the same resolved appearance value for the application and all preview controls. Keep that resolution in the existing appearance ownership boundary. **Acceptance:** dark pack + light system, light pack + dark system, explicit accent and wallpaper accent all show the color actually applied. ### 4. Home cards: several perpetual marquees compete for attention **Hallmark lens: unnecessary continuous motion.** [feature/home/HomeShelvesUi.kt:297](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/home/HomeShelvesUi.kt#L297) and [feature/home/HomeShelvesUi.kt:381](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/home/HomeShelvesUi.kt#L381). Author, title and series each use an infinite marquee on 160 dp cards. Several visible cards can animate several lines simultaneously, especially at large font sizes. This makes a recognition surface harder to scan. **Change:** preserve full-title access while reducing simultaneous movement: allow a larger card/text layout at large font sizes, or animate only the explicitly focused/selected card. Provide a static reduced-motion treatment and keep complete metadata available in details and accessibility text. Treat two-line titles as an option to evaluate, not an automatic reversal of the prior compact-card preference. **Acceptance:** a shelf of long metadata remains readable without watching multiple moving lines; reduced motion does not hide the full title. ### 5. Home cards: progress readings lack explicit meaning and room to grow **Hallmark lens: hierarchy, accessibility and responsive text.** [feature/home/HomeShelvesUi.kt:340](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/home/HomeShelvesUi.kt#L340). Elapsed time, percentage and remaining time share one unweighted row in roughly 136 dp of inner width. They are bare values, and the source explicitly acknowledges that their spoken meaning depends on order. Long durations and larger fonts have little room. **Change:** prioritize “time left” visually, or retain all three in an adaptive two-row treatment. Provide a complete card announcement that includes book identity and labels each reading; avoid a child contentDescription that replaces the book title. Keep Play as a separate accessible action. **Acceptance:** long-duration values remain intact at 2.0 font scale; TalkBack identifies the book, elapsed and remaining time, and the distinct play action. ### 6. Collection tabs: artwork uses too much of narrow cards **Hallmark lens: hierarchy and responsive allocation.** [feature/browse/SeriesListUi.kt:58](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/browse/SeriesListUi.kt#L58) and [feature/browse/SeriesListUi.kt:115](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/browse/SeriesListUi.kt#L115). Series artwork reserves 140 dp; author/genre artwork reserves 132 dp. At 320 dp with Home's outer margins and the text padding, only about 116–124 dp remains for text before a genre Edit button is added. Cards can grow vertically, but the fixed artwork makes long names unnecessarily narrow. **Change:** keep the stack/portrait/mosaic identities, but use smaller bounded artwork on narrow windows or a compact alternate layout at large font sizes. Keep the genre edit action separate from the browse target; move it to a secondary row/menu when width is insufficient. **Acceptance:** long series, author and genre names are readable without tall, narrow text columns; edit remains independently reachable. ### 7. Profile picker: switching and account maintenance have equal emphasis **Hallmark lens: action hierarchy and interaction states.** [feature/profiles/ProfileSwitcherScreen.kt:211](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/profiles/ProfileSwitcherScreen.kt#L211) and [feature/profiles/ProfileSwitcherScreen.kt:287](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/profiles/ProfileSwitcherScreen.kt#L287). Inactive cards are tappable and also contain Use, Sign out/Sign in again, and Remove in one row. Routine switching and destructive maintenance occupy the same visual tier. Busy state disables actions but does not show which profile is being switched. **Change:** make the profile identity/switch region the primary action, with a separate account menu for sign-out/removal. Keep reauthentication visible when needed and preserve the removal explanation. Display username alongside server when it differs from the display name. Add a targeted “Switching…” state and selected-state semantics; do not introduce another owner for switching policy. **Acceptance:** users can identify the active account, choose the correct same-name account on another server, and distinguish switching from removal at large text sizes. ### 8. Appearance: color choices hide useful identity and close too quickly **Hallmark lens: discoverability and state clarity.** [feature/settings/AppearanceTab.kt:378](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/settings/AppearanceTab.kt#L378) and [feature/settings/AppearanceTab.kt:555](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/settings/AppearanceTab.kt#L555). The collapsed color row shows a swatch but not the current color's visible name. Expanded swatches are named only for accessibility, selection uses a stronger ring, and each choice closes the palette. Comparing nearby colors requires repeatedly reopening it. “Follow accent” is a behavioral choice presented largely as another color. **Change:** show the selected name/source alongside the swatch, give the selected option a clear checkmark, and keep the palette open during comparison. Present Follow accent as a named source option, like the existing wallpaper option, rather than relying on its resolved hue. Preserve the 48 dp targets. **Acceptance:** the chosen color and its source are understandable without distinguishing subtle hues; comparison takes one open interaction. ## Minor findings and design refinements ### 9. Appearance: previews show backgrounds, not the resulting interface **Hallmark lens: specificity and useful feedback.** [feature/settings/AppearanceTab.kt:95](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/settings/AppearanceTab.kt#L95) and [feature/settings/AppearanceTab.kt:213](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/settings/AppearanceTab.kt#L213). Theme thumbnails show artwork or flat grounds, while glass controls expose blur values and separate card/system tint switches. They do not demonstrate their combined effect on readable text and controls. **Change:** add one small live preview using real shared card/control components, without a fake phone frame. Explain Card tint and Navigation/player tint in user terms; offer an explicit restore-defaults action. Show a platform explanation when blur is unavailable and verify the fallback rather than promising the same glass on every Android version. ### 10. Home tabs: adapt to available width, not only font scale **Hallmark lens: responsive navigation.** [feature/home/HomeScreen.kt:739](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/home/HomeScreen.kt#L739) and [feature/home/HomeScreen.kt:861](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/home/HomeScreen.kt#L861). The horizontal-to-stacked change depends only on a 1.3 font-scale threshold. Window width and translated label length can cause crowding before that threshold. **Change:** choose the arrangement using available width and label fit as well as font scale. Preserve readable labels and tap targets; allow platform-appropriate wrapping when required for accessibility rather than forcing a web-style one-line rule. Validate all four tabs with the mini-player present. ### 11. Flat list: filter and sort have the same chip treatment **Hallmark lens: hierarchy and restraint.** [feature/home/HomeScreen.kt:1070](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/home/HomeScreen.kt#L1070) and [feature/browse/BookListUi.kt:202](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/browse/BookListUi.kt#L202). Search, focused collection, filter chips and seven sort choices can accumulate in the pinned header. Filters change membership; sorting changes order, but they look like parallel categories. **Change:** retain the useful All / Continue / Downloaded filters and consider one labelled “Sort: Last played” control that opens the order choices. Show active collection scope clearly. Validate this as a density improvement rather than hiding the way out of an empty result. ### 12. Card artwork: failed URLs have a weaker fallback than absent URLs **Hallmark lens: complete image states.** [feature/browse/BookCover.kt:45](https://forgejo.homebord.org/alexander/Audiobookshelf-Manager-Claude/src/commit/8f0ff5926687b3373703ee972dbb1392a0792d63/app/src/main/kotlin/com/example/shelfplayer/feature/browse/BookCover.kt#L45). A missing URL draws the book glyph. A non-null URL uses AsyncImage without an explicit loading/error placeholder; failed requests retain the background box but lose the clear fallback symbol. Author imagery already has a more complete fallback treatment. **Change:** use the same stable cover placeholder for loading, missing and failed imagery, optionally distinguishing an actionable failure only where useful. Do not change card geometry when loading finishes. ## Recommended sequence and verification 1. Correct fixed-height rows, profile overlay clearance and appearance preview resolution. 2. Improve shelf progress readability, collection width allocation and profile action hierarchy. 3. Refine palette comparison, previews, tabs, filters and image states. Keep the canonical roadmap authoritative. This review is a candidate UI backlog, not permission to pull visual work ahead of active playback correctness. Verify on Android at 320/375/414/768 dp widths and larger tablet windows, font scales 1.0/1.3/2.0, portrait/landscape, long English/Norwegian labels, light/dark/AMOLED/background packs, and reduced motion. Include offline/missing covers, long metadata, signed-out and locked profiles, and active playback. Test TalkBack order, selection, expanded/collapsed state, separate nested actions and touch targets. Verify actual glass/background contrast and pre-Android-12 fallback separately. **Verdict:** preserve the visual identity and meaningful card families; improve adaptive geometry and make actions and appearance choices easier to understand. **0 new critical · 8 major · 4 minor.**
Author
Owner

The deeper Home cards/tabs/flat-list, profile-picker and Appearance review now has a dedicated issue: #48. It includes all 12 findings and a Hallmark recommendation for a calmer, cover-led library interface. Track that scope in #48; this issue retains the original contrast, compact-player and recovery findings. Other Settings tabs remain excluded.

The deeper Home cards/tabs/flat-list, profile-picker and Appearance review now has a dedicated issue: #48. It includes all 12 findings and a Hallmark recommendation for a calmer, cover-led library interface. Track that scope in #48; this issue retains the original contrast, compact-player and recovery findings. Other Settings tabs remain excluded.
Author
Owner

2026-09-27 accepted refinement

The owner accepted the current Hallmark direction and clarified actual player usage.

Dedicated child issues now own the implementation detail:

  • #96 — mini-player: prioritize Sleep Timer + Play/Pause; remove permanent Back/Forward/Stop from compact chrome.
  • #97 — full player: keep primary skip/play transport, but make History the strongest secondary navigation action and demote Bookmarks.

These user-priority decisions supersede this audit's earlier generic suggestion to retain compact skips in the mini-player. Keep #47 as the broader audit/contrast/seek/recovery staging issue; avoid implementing the same visual work twice.

## 2026-09-27 accepted refinement The owner accepted the current Hallmark direction and clarified actual player usage. Dedicated child issues now own the implementation detail: - #96 — mini-player: prioritize **Sleep Timer + Play/Pause**; remove permanent Back/Forward/Stop from compact chrome. - #97 — full player: keep primary skip/play transport, but make **History** the strongest secondary navigation action and demote Bookmarks. These user-priority decisions supersede this audit's earlier generic suggestion to retain compact skips in the mini-player. Keep #47 as the broader audit/contrast/seek/recovery staging issue; avoid implementing the same visual work twice.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
alexander/Audiobookshelf-Manager-Claude#47
No description provided.