[Hallmark] Establish a coherent app-wide navigation and motion language #101

Open
opened 2026-09-27 14:48:19 +02:00 by alexander · 3 comments
Owner

Purpose

Define and implement a small, consistent navigation/motion vocabulary for BookWave so transitions explain hierarchy without making the app feel animated for its own sake.

This is the parent/staging issue for app-wide route motion. Focused player expansion is tracked separately. Existing Home/Settings visual redesign issues remain authoritative for their local UI.

Reviewed against current main at f9f7feba8e7bb499c6001bf0cc19a38357b7494a on 2026-09-27.

Design principle

BookWave should use motion to explain where the user is going:

  • Home axes move horizontally because they are sibling views of the same library.
  • Detail destinations move shallowly forward/back because the user is drilling into content.
  • The full player rises because it is a temporary layer over the current screen.
  • Bottom sheets rise because they are temporary tools.
  • Ordinary state changes should mostly stay still.

Avoid decorative bounce, gratuitous parallax, full-screen theatrical slides and unrelated one-off animation specs.

1. Add shallow route-depth transitions

The current ShelfPlayerNavHost defines routes without an explicit BookWave transition contract.

Prototype a restrained push/pop treatment for detail navigation such as:

  • Home → Book;
  • Series → Book;
  • Author → Book;
  • Book → Series / Author;
  • Book → Edit metadata.

Preferred feel:

  • incoming detail moves only a small fraction from the trailing edge plus a subtle opacity transition;
  • outgoing screen moves less;
  • Back reverses the relationship;
  • do not use full-width iOS-style page slides.

Utility destinations such as Profiles / Settings / Downloads may use a quieter fade or very shallow movement because they represent a task change rather than deeper content hierarchy.

2. Support predictive Back

Where Android/Navigation Compose supports it, route transitions should track predictive-back progress instead of waiting for gesture completion.

Requirements:

  • Back gesture should reveal the previous destination progressively where appropriate;
  • ordinary button/toolbar Back must produce the same final navigation result;
  • custom player behavior is tracked separately and should integrate with the same motion language;
  • modal Material components should retain their native predictive-back behavior rather than being replaced with custom sheets.

Do not break existing navigation-stack semantics or sign-in popUpTo behavior.

3. Establish a tiny shared motion vocabulary

Create/reuse semantic animation specs rather than choosing spring/tween behavior independently in each screen.

Suggested roles to prototype, not hard-coded release values:

  • Micro: ~120–160ms — chevrons, selection/icon-state changes;
  • Standard: ~180–240ms — inline disclosure, compact route/state changes;
  • Large: ~220–300ms — substantial overlays/player layer;
  • Gesture-driven: pager, edge resistance and predictive Back follow the finger rather than chasing it.

Rule:

  • no overshoot for ordinary UI state;
  • a dragged physical surface may use a restrained return-to-rest response;
  • functional progress/load indicators may continue while work is active.

4. Reduced-motion contract

Verify all BookWave-owned spatial motion with Android animation/motion scale reduced or disabled.

Reduced motion must preserve:

  • state understanding;
  • destination identity;
  • accessibility focus;
  • progress/loading truth.

Continuous decorative motion should stop or collapse where the platform requests reduced motion. Functional progress indicators may remain functional.

Explicitly verify:

  • Home pager tap/swipe;
  • route push/pop;
  • Settings disclosures;
  • edge overspill;
  • mini/full player transitions;
  • marquees owned by #95/#96;
  • sync/download progress indicators.

Do not add a BookWave-specific Reduce Motion preference unless platform behavior proves insufficient.

5. Keep good gesture-driven motion

Preserve the current Home axis design:

  • pager follows the finger;
  • adjacent page is visible during drag;
  • selection pill follows fractional pager position directly;
  • abandoned swipe returns with the pager rather than a second independent animation.

Preserve edge resistance as feedback at pager bounds, subject to #95's separate persistent-nav bounce cleanup.

Implementation starting points

  • app/src/main/kotlin/com/example/shelfplayer/navigation/ShelfPlayerNavHost.kt
  • app/src/main/kotlin/com/example/shelfplayer/ui/gesture/EdgeOverspill.kt
  • shared design-system motion definitions if introduced
  • focused screens only where they need to adopt the shared specs

Do not refactor unrelated navigation architecture merely to centralize animation values.

Acceptance

  • Forward/back hierarchy is visually understandable without becoming theatrical.
  • Predictive Back tracks the gesture on supported Android versions.
  • Back buttons, system Back and predictive Back all resolve to the same destinations.
  • Home swipe behavior remains direct and finger-tracked.
  • Utility destinations do not masquerade as content drill-down.
  • Reduced/disabled animation scale remains usable.
  • No bounce/elastic motion remains on ordinary persistent UI.
  • Validate 320/375/414/768dp, portrait/landscape/tablet, TalkBack and active mini-player.
  • Add focused navigation tests for stack semantics and device/rendered evidence for motion itself.

This issue defines the app-wide language. Child/local issues should consume it rather than inventing competing motion systems.

## Purpose Define and implement a small, consistent navigation/motion vocabulary for BookWave so transitions explain hierarchy without making the app feel animated for its own sake. This is the parent/staging issue for app-wide route motion. Focused player expansion is tracked separately. Existing Home/Settings visual redesign issues remain authoritative for their local UI. Reviewed against current `main` at `f9f7feba8e7bb499c6001bf0cc19a38357b7494a` on 2026-09-27. ## Design principle BookWave should use motion to explain **where the user is going**: - Home axes move horizontally because they are sibling views of the same library. - Detail destinations move shallowly forward/back because the user is drilling into content. - The full player rises because it is a temporary layer over the current screen. - Bottom sheets rise because they are temporary tools. - Ordinary state changes should mostly stay still. Avoid decorative bounce, gratuitous parallax, full-screen theatrical slides and unrelated one-off animation specs. ## 1. Add shallow route-depth transitions The current `ShelfPlayerNavHost` defines routes without an explicit BookWave transition contract. Prototype a restrained push/pop treatment for detail navigation such as: - Home → Book; - Series → Book; - Author → Book; - Book → Series / Author; - Book → Edit metadata. Preferred feel: - incoming detail moves only a small fraction from the trailing edge plus a subtle opacity transition; - outgoing screen moves less; - Back reverses the relationship; - do not use full-width iOS-style page slides. Utility destinations such as Profiles / Settings / Downloads may use a quieter fade or very shallow movement because they represent a task change rather than deeper content hierarchy. ## 2. Support predictive Back Where Android/Navigation Compose supports it, route transitions should track predictive-back progress instead of waiting for gesture completion. Requirements: - Back gesture should reveal the previous destination progressively where appropriate; - ordinary button/toolbar Back must produce the same final navigation result; - custom player behavior is tracked separately and should integrate with the same motion language; - modal Material components should retain their native predictive-back behavior rather than being replaced with custom sheets. Do not break existing navigation-stack semantics or sign-in `popUpTo` behavior. ## 3. Establish a tiny shared motion vocabulary Create/reuse semantic animation specs rather than choosing spring/tween behavior independently in each screen. Suggested roles to prototype, not hard-coded release values: - **Micro:** ~120–160ms — chevrons, selection/icon-state changes; - **Standard:** ~180–240ms — inline disclosure, compact route/state changes; - **Large:** ~220–300ms — substantial overlays/player layer; - **Gesture-driven:** pager, edge resistance and predictive Back follow the finger rather than chasing it. Rule: - no overshoot for ordinary UI state; - a dragged physical surface may use a restrained return-to-rest response; - functional progress/load indicators may continue while work is active. ## 4. Reduced-motion contract Verify all BookWave-owned spatial motion with Android animation/motion scale reduced or disabled. Reduced motion must preserve: - state understanding; - destination identity; - accessibility focus; - progress/loading truth. Continuous decorative motion should stop or collapse where the platform requests reduced motion. Functional progress indicators may remain functional. Explicitly verify: - Home pager tap/swipe; - route push/pop; - Settings disclosures; - edge overspill; - mini/full player transitions; - marquees owned by #95/#96; - sync/download progress indicators. Do not add a BookWave-specific Reduce Motion preference unless platform behavior proves insufficient. ## 5. Keep good gesture-driven motion Preserve the current Home axis design: - pager follows the finger; - adjacent page is visible during drag; - selection pill follows fractional pager position directly; - abandoned swipe returns with the pager rather than a second independent animation. Preserve edge resistance as feedback at pager bounds, subject to #95's separate persistent-nav bounce cleanup. ## Implementation starting points - `app/src/main/kotlin/com/example/shelfplayer/navigation/ShelfPlayerNavHost.kt` - `app/src/main/kotlin/com/example/shelfplayer/ui/gesture/EdgeOverspill.kt` - shared design-system motion definitions if introduced - focused screens only where they need to adopt the shared specs Do not refactor unrelated navigation architecture merely to centralize animation values. ## Acceptance - Forward/back hierarchy is visually understandable without becoming theatrical. - Predictive Back tracks the gesture on supported Android versions. - Back buttons, system Back and predictive Back all resolve to the same destinations. - Home swipe behavior remains direct and finger-tracked. - Utility destinations do not masquerade as content drill-down. - Reduced/disabled animation scale remains usable. - No bounce/elastic motion remains on ordinary persistent UI. - Validate 320/375/414/768dp, portrait/landscape/tablet, TalkBack and active mini-player. - Add focused navigation tests for stack semantics and device/rendered evidence for motion itself. This issue defines the app-wide language. Child/local issues should consume it rather than inventing competing motion systems.
Author
Owner

Consume rather than duplicate these local owners:

  • #95 — Home chrome/shelf motion; includes removal of persistent nav-capsule overshoot.
  • #96 — mini-player composition and non-bouncy entrance.
  • #99 — Settings explicit Back/navigation and quieter category switching.
  • #102 — full-player expansion/collapse and predictive Back.
  • #103 — contextual Back affordance for pushed Sign-in.
  • #104 — optional shared book-cover transition after core layouts stabilize.

#101 owns the shared vocabulary and route-level behavior, not those screens' visual redesigns.

## Related focused issues Consume rather than duplicate these local owners: - #95 — Home chrome/shelf motion; includes removal of persistent nav-capsule overshoot. - #96 — mini-player composition and non-bouncy entrance. - #99 — Settings explicit Back/navigation and quieter category switching. - #102 — full-player expansion/collapse and predictive Back. - #103 — contextual Back affordance for pushed Sign-in. - #104 — optional shared book-cover transition after core layouts stabilize. #101 owns the shared vocabulary and route-level behavior, not those screens' visual redesigns.
Author
Owner

Hallmark Slice 1 — player-only subset adopted

This slice consumes only the player subset of #101:

  • semantic roles: Micro / Standard / Large / Gesture-driven;
  • no-bounce rule for persistent/player chrome;
  • Large bottom-up overlay transition for full-player expansion/collapse;
  • gesture-driven predictive Back that follows progress;
  • reduced-motion contract through platform/Compose animation scaling.

No app-wide route transitions, Home/Book navigation changes, Settings motion or sign-in navigation work are included. #101 remains open as the parent contract.

## Hallmark Slice 1 — player-only subset adopted This slice consumes only the player subset of #101: - semantic roles: Micro / Standard / Large / Gesture-driven; - no-bounce rule for persistent/player chrome; - Large bottom-up overlay transition for full-player expansion/collapse; - gesture-driven predictive Back that follows progress; - reduced-motion contract through platform/Compose animation scaling. No app-wide route transitions, Home/Book navigation changes, Settings motion or sign-in navigation work are included. #101 remains open as the parent contract.
Author
Owner

Hallmark Slice 1 — implemented player subset

Branch mcp/hallmark-slice-1-player now consumes the player-only portion of #101 at HEAD f4f90f10a624e310cb87d6abe20482aea444bcb2:

  • semantic player motion vocabulary with Micro / Standard / Large / gesture-driven roles;
  • non-overshooting tween motion; no ordinary player bounce;
  • Standard motion for compact player/inset state;
  • Large bottom-up overlay motion for full-player expansion/collapse;
  • gesture-driven predictive Back;
  • platform animation-duration scaling remains the reduced-motion authority;
  • motion is limited to transforms/opacity where it explains hierarchy.

No Home→Book, Settings, Sign-in or other app-wide navigation transition work was included. #101 remains open.

Hallmark code-level review: Philosophy 5/5 · Hierarchy 5/5 · Execution 4/5 · Specificity 5/5 · Restraint 5/5 · Variety 4/5. Execution is intentionally held below 5 because rendered/device acceptance was not run under the owner's no-checks instruction.

## Hallmark Slice 1 — implemented player subset Branch `mcp/hallmark-slice-1-player` now consumes the player-only portion of #101 at HEAD `f4f90f10a624e310cb87d6abe20482aea444bcb2`: - semantic player motion vocabulary with Micro / Standard / Large / gesture-driven roles; - non-overshooting tween motion; no ordinary player bounce; - Standard motion for compact player/inset state; - Large bottom-up overlay motion for full-player expansion/collapse; - gesture-driven predictive Back; - platform animation-duration scaling remains the reduced-motion authority; - motion is limited to transforms/opacity where it explains hierarchy. No Home→Book, Settings, Sign-in or other app-wide navigation transition work was included. #101 remains open. Hallmark code-level review: Philosophy 5/5 · Hierarchy 5/5 · Execution 4/5 · Specificity 5/5 · Restraint 5/5 · Variety 4/5. Execution is intentionally held below 5 because rendered/device acceptance was not run under the owner's no-checks instruction.
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#101
No description provided.