[UI] Add a consistent finished-book visual indicator to book cards #86

Open
opened 2026-09-24 05:53:41 +02:00 by alexander · 1 comment
Owner

Product intent

Make a finished audiobook immediately recognizable while browsing, especially inside a series, without turning BookWave's calm cover-led UI into a field of badges.

This issue is the design/implementation staging area for the finished-book treatment. Do not treat the first visual proposal below as frozen until it has been rendered against the current themes and the planned card-appearance controls.

Current evidence

Reviewed current main at ca080a875f95e7e50a3944e1810cf9c76194c167.

  • BookCard already has an authoritative completion signal: book.progress?.isFinished == true.
  • The shared list/series BookCard already renders the text “Finished”, but the state is easy to miss when scanning covers/cards.
  • Shared glass cards currently use a subtle 1 dp outlineVariant border and 12 dp corner radius.
  • BookCard is shared by general browsing and series/author surfaces; Home also has its own book-card composition, so implementation must inventory all book-card families, not fix only the series screen.
  • Related UI direction: #48 and #50.

Preferred: semantic completion edge

Use a small green completion accent on the card edge, separate from the normal decorative card border.

Suggested starting treatment:

  • a restrained green/positive-status edge accent, approximately 2–3 dp visually;
  • concentrated on one edge or corner rather than a bright full neon outline;
  • optionally a very soft outward glow/halo at low alpha;
  • follows the current card shape when rounded;
  • remains legible when the user later chooses square/less-rounded cards;
  • does not replace the existing “Finished” text where that text is already useful.

This is closest to the current glass design: it adds one semantic signal without adding another panel, chip, or permanent icon over cover art.

Candidate alternatives to compare

  1. Corner completion stroke — green accent only across the upper/right corner. Quietest and least likely to compete with cover art.
  2. Leading-edge completion rail — 2–3 dp green rail on the outer edge of the card. Very scannable in a series list and survives a disabled decorative border.
  3. Small check-dot — a tiny green circular check near the card edge, not on top of important cover artwork. Stronger non-color cue for accessibility, but visually busier.
  4. Soft completed tint — extremely subtle positive-color wash behind the card. Lower preference because future “card background off” settings would make it inconsistent and it can muddy artwork/background themes.
  5. Full green outline/glow — easy to see, but lower preference because a full luminous ring is likely too loud beside BookWave's existing glass hairline.

Prototype edge rail/corner stroke + existing Finished text. If color-only identification is insufficient in accessibility review, add a very small check glyph/dot as the non-color companion rather than strengthening the glow.

Important interaction with planned card appearance controls

The completion indicator is semantic state, not decorative card chrome.

Therefore it must remain visible and correct when the future Appearance setting allows:

  • card border off;
  • card background/tint off;
  • different card corner roundness, including nearly square cards.

Do not implement “finished” by recoloring the normal optional border. Give completion its own layer/token so users can hide decorative borders without hiding status.

Scope

  • Show the completed treatment on all finished book cards, not only books opened through Series.
  • Series view is the primary motivating case and should make sequence scanning obviously better.
  • Audit Home shelves, flat Books list, Series book rows, Author book rows, search/focused collection results, and any other shared book-card presentation.
  • Use the existing authoritative completion state. Do not invent a local percentage threshold.
  • Preserve normal pressed/focused/selected states and active-playback indication if present.
  • Do not tint or mark series/author/genre collection cards merely because all contained books happen to be finished; this issue is about individual books.

Accessibility

  • Never rely on green alone to communicate completion.
  • Existing readable “Finished” text can satisfy the non-color cue where present.
  • Where compact Home cards do not expose that text, evaluate a small check glyph or equivalent semantic treatment.
  • TalkBack/card semantics should expose that the book is finished without causing duplicate “finished, finished” announcements.
  • Positive-state green must retain usable contrast in Light, Dark, AMOLED, dynamic color and artwork-background themes.

Acceptance criteria

  • A user can scan a Series and distinguish finished from unfinished books without opening a book.
  • The same completion language is coherent across every book-card family.
  • Indicator uses book.progress.isFinished / the existing authoritative completion model.
  • It remains visible with decorative card border disabled, card background/tint disabled, and low/zero corner roundness.
  • It does not obscure cover artwork, title, progress, Play controls, focus/pressed state or selection.
  • Verify Light, Dark, AMOLED, bundled backgrounds, dynamic color, narrow/wide screens and large text.
  • Verify finished, unfinished, never-started and in-progress cards side by side.
  • Add focused rendering/semantics tests where practical and physical screenshot comparison before final visual choice.

Staging decisions

  • Direction: subtle semantic edge treatment, not a large badge.
  • Preferred first prototype: small green edge rail or corner stroke with a very soft glow.
  • Architecture constraint: completion decoration must be independent from the optional decorative card border/background.
  • Still to decide after rendering: rail vs corner stroke; exact thickness/alpha; whether compact Home cards need a tiny check glyph in addition to color.
## Product intent Make a finished audiobook immediately recognizable while browsing, especially inside a series, without turning BookWave's calm cover-led UI into a field of badges. This issue is the **design/implementation staging area** for the finished-book treatment. Do not treat the first visual proposal below as frozen until it has been rendered against the current themes and the planned card-appearance controls. ## Current evidence Reviewed current `main` at `ca080a875f95e7e50a3944e1810cf9c76194c167`. - `BookCard` already has an authoritative completion signal: `book.progress?.isFinished == true`. - The shared list/series `BookCard` already renders the text “Finished”, but the state is easy to miss when scanning covers/cards. - Shared glass cards currently use a subtle 1 dp `outlineVariant` border and 12 dp corner radius. - `BookCard` is shared by general browsing and series/author surfaces; Home also has its own book-card composition, so implementation must inventory **all book-card families**, not fix only the series screen. - Related UI direction: #48 and #50. ## Recommended visual direction ### Preferred: semantic completion edge Use a **small green completion accent on the card edge**, separate from the normal decorative card border. Suggested starting treatment: - a restrained green/positive-status edge accent, approximately 2–3 dp visually; - concentrated on one edge or corner rather than a bright full neon outline; - optionally a very soft outward glow/halo at low alpha; - follows the current card shape when rounded; - remains legible when the user later chooses square/less-rounded cards; - does **not** replace the existing “Finished” text where that text is already useful. This is closest to the current glass design: it adds one semantic signal without adding another panel, chip, or permanent icon over cover art. ### Candidate alternatives to compare 1. **Corner completion stroke** — green accent only across the upper/right corner. Quietest and least likely to compete with cover art. 2. **Leading-edge completion rail** — 2–3 dp green rail on the outer edge of the card. Very scannable in a series list and survives a disabled decorative border. 3. **Small check-dot** — a tiny green circular check near the card edge, not on top of important cover artwork. Stronger non-color cue for accessibility, but visually busier. 4. **Soft completed tint** — extremely subtle positive-color wash behind the card. Lower preference because future “card background off” settings would make it inconsistent and it can muddy artwork/background themes. 5. **Full green outline/glow** — easy to see, but lower preference because a full luminous ring is likely too loud beside BookWave's existing glass hairline. ### Recommended combination to prototype first Prototype **edge rail/corner stroke + existing Finished text**. If color-only identification is insufficient in accessibility review, add a very small check glyph/dot as the non-color companion rather than strengthening the glow. ## Important interaction with planned card appearance controls The completion indicator is **semantic state**, not decorative card chrome. Therefore it must remain visible and correct when the future Appearance setting allows: - card border off; - card background/tint off; - different card corner roundness, including nearly square cards. Do not implement “finished” by recoloring the normal optional border. Give completion its own layer/token so users can hide decorative borders without hiding status. ## Scope - Show the completed treatment on **all finished book cards**, not only books opened through Series. - Series view is the primary motivating case and should make sequence scanning obviously better. - Audit Home shelves, flat Books list, Series book rows, Author book rows, search/focused collection results, and any other shared book-card presentation. - Use the existing authoritative completion state. Do not invent a local percentage threshold. - Preserve normal pressed/focused/selected states and active-playback indication if present. - Do not tint or mark series/author/genre collection cards merely because all contained books happen to be finished; this issue is about individual books. ## Accessibility - Never rely on green alone to communicate completion. - Existing readable “Finished” text can satisfy the non-color cue where present. - Where compact Home cards do not expose that text, evaluate a small check glyph or equivalent semantic treatment. - TalkBack/card semantics should expose that the book is finished without causing duplicate “finished, finished” announcements. - Positive-state green must retain usable contrast in Light, Dark, AMOLED, dynamic color and artwork-background themes. ## Acceptance criteria - A user can scan a Series and distinguish finished from unfinished books without opening a book. - The same completion language is coherent across every book-card family. - Indicator uses `book.progress.isFinished` / the existing authoritative completion model. - It remains visible with decorative card border disabled, card background/tint disabled, and low/zero corner roundness. - It does not obscure cover artwork, title, progress, Play controls, focus/pressed state or selection. - Verify Light, Dark, AMOLED, bundled backgrounds, dynamic color, narrow/wide screens and large text. - Verify finished, unfinished, never-started and in-progress cards side by side. - Add focused rendering/semantics tests where practical and physical screenshot comparison before final visual choice. ## Staging decisions - **Direction:** subtle semantic edge treatment, not a large badge. - **Preferred first prototype:** small green edge rail or corner stroke with a very soft glow. - **Architecture constraint:** completion decoration must be independent from the optional decorative card border/background. - **Still to decide after rendering:** rail vs corner stroke; exact thickness/alpha; whether compact Home cards need a tiny check glyph in addition to color.
Author
Owner

Related appearance-control staging: #87. The finished indicator must remain semantic and visible when #87 disables decorative card borders/backgrounds or changes corner roundness.

Related appearance-control staging: #87. The finished indicator must remain semantic and visible when #87 disables decorative card borders/backgrounds or changes corner roundness.
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#86
No description provided.