[Appearance] Add Home card roundness, border and background controls #87

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

Product intent

Let users tune how prominent BookWave's Home cards feel without changing their content hierarchy: choose card corner roundness and independently decide whether the card's decorative border and background/tint are shown.

This issue is the design/implementation staging area for these card appearance controls and should stay coordinated with #48 and the finished-book indicator issue created alongside it.

Current evidence

Reviewed current main at ca080a875f95e7e50a3944e1810cf9c76194c167.

The shared glass card currently has hard-coded chrome:

  • GlassDefaults.CardCornerRadius = 12.dp;
  • Modifier.cardGlass() always draws a 1 dp outlineVariant border;
  • card glass/tint can already be switched through cardGlassTintEnabled;
  • Appearance already owns Theme → Colour → Glass → Language state through AppearanceRepository;
  • Home book cards use GlassCard, while other surfaces also reuse it.

#48 already proposes making Appearance a clearer live preview tool. This issue is narrower: define and persist the card-shape/chrome preferences themselves.

Proposed controls

1. Card roundness

Add a user-facing control for Home card corner roundness.

Preferred interaction: a slider or small named scale with a live preview, rather than a long list of arbitrary dp numbers.

Candidate scale to prototype:

  • Square — 0 dp
  • Subtle — ~6 dp
  • Default — 12 dp
  • Rounded — ~18 dp
  • Soft — ~24 dp

Implementation may store a bounded numeric value or a stable enum; the UI should use understandable labels and keep the current 12 dp look as the default/migration value.

2. Show card border

Add an independent Card border switch.

  • On: draw the existing subtle hairline/outline treatment.
  • Off: remove only decorative card outline chrome.
  • Semantic status indicators (for example the separate finished-book completion edge) must remain visible.

3. Show card background

Add an independent Card background switch.

This needs a precise product definition before implementation because the current glass system has both blur and tint/fallback behavior.

Recommended meaning:

  • On: card may draw its current glass/tinted/fallback surface behind content.
  • Off: card content sits directly over the app backdrop, subject to a readability fallback only where platform limitations would otherwise make content illegible.

Do not silently make “background off” another name for “card tint off” unless rendered investigation proves those concepts are indistinguishable to users. The existing Card tint preference should either remain a separate advanced control or be deliberately reconciled/migrated as part of this issue.

Scope decision to stage

The request is specifically for Home-screen cards. Start with Home as the product scope and design the preference model so it can be safely reused by other card families later.

Before implementation, inventory which GlassCard uses are truly content cards versus settings groups/chrome. Do not globally square/strip every GlassCard merely because they share a primitive.

Recommended architecture:

  • expose semantic card appearance values (shape/roundness, decorative border enabled, card background enabled) through the existing appearance state;
  • Home/card components opt into those values;
  • settings groups, dialogs and unrelated structural surfaces keep their own appropriate shape/chrome unless explicitly brought into scope later.

Live preview

Coordinate with #48's proposed Appearance preview. These controls are hard to judge from labels alone.

Preview should show an actual BookWave-style book card and update live for:

  • roundness;
  • border on/off;
  • background on/off;
  • card tint/blur interaction;
  • current theme/background pack.

Avoid a fake device frame.

Interaction with semantic states

Decorative preferences must not erase state.

In particular:

  • finished-book indicator remains visible with border off/background off;
  • selected/focused/pressed states remain perceivable;
  • active playback/status styling remains distinct;
  • accessibility semantics never depend on the decorative border/background.

Storage / migration

  • Preserve the existing visual result for current users by default: 12 dp rounded card, decorative border on, current background behavior on.
  • Persist through the existing Appearance repository/DataStore boundary.
  • Add forward-compatible values/defaults rather than scattering raw dp/booleans through composables.
  • Resolve any relationship with the existing cardGlassTintEnabled preference explicitly and test migration/default behavior.

Acceptance criteria

  • Appearance exposes understandable controls for Home card roundness, border visibility and background visibility.
  • Existing users see the current card look until they change a setting.
  • Roundness updates Home cards consistently without clipping artwork/actions or breaking touch targets.
  • Border off removes decorative outline only.
  • Background off has a defined, tested result across Android blur-capable and fallback paths.
  • Finished/status/focus/pressed semantics survive every combination.
  • Verify combinations in Light, Dark, AMOLED, dynamic color and bundled artwork themes.
  • Verify at 320/375/414/768 dp and large text.
  • Preview accurately matches the actual Home card result.
  • Automated state/persistence tests cover defaults and saved values; rendered/device checks cover visual combinations.

Staging decisions / open questions

  • Default roundness: keep current 12 dp.
  • Recommended UI: named/stepped roundness control with live preview.
  • Border and background: independent switches.
  • Architecture: Home opt-in first; do not blindly change every shared GlassCard.
  • Open: whether existing “Card tint” remains separate, is renamed, or is folded into “Card background”. Decide from rendered behavior and migration impact, not terminology alone.
  • Open: exact maximum radius and whether the control is discrete or continuous.
## Product intent Let users tune how prominent BookWave's Home cards feel without changing their content hierarchy: choose card corner roundness and independently decide whether the card's decorative border and background/tint are shown. This issue is the **design/implementation staging area** for these card appearance controls and should stay coordinated with #48 and the finished-book indicator issue created alongside it. ## Current evidence Reviewed current `main` at `ca080a875f95e7e50a3944e1810cf9c76194c167`. The shared glass card currently has hard-coded chrome: - `GlassDefaults.CardCornerRadius = 12.dp`; - `Modifier.cardGlass()` always draws a 1 dp `outlineVariant` border; - card glass/tint can already be switched through `cardGlassTintEnabled`; - Appearance already owns Theme → Colour → Glass → Language state through `AppearanceRepository`; - Home book cards use `GlassCard`, while other surfaces also reuse it. #48 already proposes making Appearance a clearer live preview tool. This issue is narrower: define and persist the card-shape/chrome preferences themselves. ## Proposed controls ### 1. Card roundness Add a user-facing control for Home card corner roundness. Preferred interaction: a slider or small named scale with a live preview, rather than a long list of arbitrary dp numbers. Candidate scale to prototype: - **Square** — 0 dp - **Subtle** — ~6 dp - **Default** — 12 dp - **Rounded** — ~18 dp - **Soft** — ~24 dp Implementation may store a bounded numeric value or a stable enum; the UI should use understandable labels and keep the current 12 dp look as the default/migration value. ### 2. Show card border Add an independent **Card border** switch. - On: draw the existing subtle hairline/outline treatment. - Off: remove only decorative card outline chrome. - Semantic status indicators (for example the separate finished-book completion edge) must remain visible. ### 3. Show card background Add an independent **Card background** switch. This needs a precise product definition before implementation because the current glass system has both blur and tint/fallback behavior. Recommended meaning: - On: card may draw its current glass/tinted/fallback surface behind content. - Off: card content sits directly over the app backdrop, subject to a readability fallback only where platform limitations would otherwise make content illegible. Do not silently make “background off” another name for “card tint off” unless rendered investigation proves those concepts are indistinguishable to users. The existing Card tint preference should either remain a separate advanced control or be deliberately reconciled/migrated as part of this issue. ## Scope decision to stage The request is specifically for **Home-screen cards**. Start with Home as the product scope and design the preference model so it can be safely reused by other card families later. Before implementation, inventory which `GlassCard` uses are truly content cards versus settings groups/chrome. Do **not** globally square/strip every `GlassCard` merely because they share a primitive. Recommended architecture: - expose semantic card appearance values (shape/roundness, decorative border enabled, card background enabled) through the existing appearance state; - Home/card components opt into those values; - settings groups, dialogs and unrelated structural surfaces keep their own appropriate shape/chrome unless explicitly brought into scope later. ## Live preview Coordinate with #48's proposed Appearance preview. These controls are hard to judge from labels alone. Preview should show an actual BookWave-style book card and update live for: - roundness; - border on/off; - background on/off; - card tint/blur interaction; - current theme/background pack. Avoid a fake device frame. ## Interaction with semantic states Decorative preferences must not erase state. In particular: - finished-book indicator remains visible with border off/background off; - selected/focused/pressed states remain perceivable; - active playback/status styling remains distinct; - accessibility semantics never depend on the decorative border/background. ## Storage / migration - Preserve the existing visual result for current users by default: 12 dp rounded card, decorative border on, current background behavior on. - Persist through the existing Appearance repository/DataStore boundary. - Add forward-compatible values/defaults rather than scattering raw dp/booleans through composables. - Resolve any relationship with the existing `cardGlassTintEnabled` preference explicitly and test migration/default behavior. ## Acceptance criteria - Appearance exposes understandable controls for Home card roundness, border visibility and background visibility. - Existing users see the current card look until they change a setting. - Roundness updates Home cards consistently without clipping artwork/actions or breaking touch targets. - Border off removes decorative outline only. - Background off has a defined, tested result across Android blur-capable and fallback paths. - Finished/status/focus/pressed semantics survive every combination. - Verify combinations in Light, Dark, AMOLED, dynamic color and bundled artwork themes. - Verify at 320/375/414/768 dp and large text. - Preview accurately matches the actual Home card result. - Automated state/persistence tests cover defaults and saved values; rendered/device checks cover visual combinations. ## Staging decisions / open questions - **Default roundness:** keep current 12 dp. - **Recommended UI:** named/stepped roundness control with live preview. - **Border and background:** independent switches. - **Architecture:** Home opt-in first; do not blindly change every shared `GlassCard`. - **Open:** whether existing “Card tint” remains separate, is renamed, or is folded into “Card background”. Decide from rendered behavior and migration impact, not terminology alone. - **Open:** exact maximum radius and whether the control is discrete or continuous.
Author
Owner

Related completion-state staging: #86. Card chrome preferences must not hide or replace the semantic finished-book indicator.

Related completion-state staging: #86. Card chrome preferences must not hide or replace the semantic finished-book indicator.
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#87
No description provided.