designmd-forge 1.2.0

package/dist/data/designs/ios-kindle-android.md

@@ -0,0 +1,439 @@
+# Kindle (iOS) — Jetpack Compose Implementation Guide
+
+Companion to [DESIGN.md](DESIGN.md) — the framework-neutral spec. This file ports Kindle's visual language to **Android with Jetpack Compose (Material 3)**: a color token object, a reading-theme model, a `Typography` set, paste-ready `@Composable`s, the reader + Aa panel, motion, and haptics.
+
+> Why a Compose guide for an iOS-referenced app? The DESIGN.md tokens are platform-neutral. This file keeps the *visual* identity (Kindle's vanishing chrome, sepia reading page, one-orange accent, cover-grid library with progress bars) while making everything idiomatic Android — `NavigationBar` instead of a UITabBar, `ModalBottomSheet` instead of a SwiftUI sheet, `sp`/`dp` instead of `pt`.
+
+Assumes Compose BOM `2024.09+`, Kotlin `2.0+`, `minSdk 24`, Material 3, and [Coil](https://coil-kt.github.io/coil/) `2.6+` for cover art. No color extraction — Kindle's palette is fixed; Palette is not needed. Kindle has two surface contexts: the **reading surface** obeys the user's chosen theme (OS-independent); the **app chrome** follows system dark.
+
+## 1. Color Tokens
+
+```kotlin
+// ui/theme/KindleColors.kt
+import androidx.compose.ui.graphics.Color
+
+object KindleColors {
+    // Brand & interactive — orange is the ONLY accent
+    val Orange        = Color(0xFFFF9900)
+    val OrangePressed = Color(0xFFE88B00)
+    val Black         = Color(0xFF1A1A1A)
+    val Link          = Color(0xFF1A98FF)
+    val KindleBlue    = Color(0xFF4FB3D9)
+
+    // App chrome (light)
+    val ChromeCanvas  = Color(0xFFFFFFFF)
+    val SurfaceSubtle = Color(0xFFF4F2EE)
+    val Divider       = Color(0xFFE4E2DD)
+
+    // App chrome (dark)
+    val DarkCanvas   = Color(0xFF0E0E0E)
+    val DarkSurface1 = Color(0xFF1A1A1A)
+    val DarkSurface2 = Color(0xFF242424)
+    val DarkDivider  = Color(0xFF2E2E2E)
+
+    // Text (chrome)
+    val TextPrimary     = Color(0xFF1A1A1A)
+    val TextSecondary   = Color(0xFF6B6B6B)
+    val DarkTextPrimary = Color(0xFFE8E8E8)
+    val DarkTextSecondary = Color(0xFF9A9A9A)
+
+    // Semantic
+    val Error   = Color(0xFFE0533D)
+    val Success = Color(0xFF2FAE5F)
+}
+
+// Reading themes — the user's choice, NOT the OS
+enum class KindleReadingTheme(val page: Color, val ink: Color) {
+    White(Color(0xFFFFFFFF), Color(0xFF1A1A1A)),
+    Sepia(Color(0xFFFBF0D9), Color(0xFF5F4B32)),   // default
+    Green(Color(0xFFC5E1C5), Color(0xFF33492F)),
+    Dark (Color(0xFF2A2A2A), Color(0xFFD8D8D8)),
+    Black(Color(0xFF000000), Color(0xFFC8C8C8)),   // dimmed ink, not white
+}
+```
+
+Wire app chrome into both schemes. The reading surface does NOT read the Material scheme — it renders the user's `KindleReadingTheme`.
+
+```kotlin
+// ui/theme/Theme.kt
+import androidx.compose.foundation.isSystemInDarkTheme
+import androidx.compose.material3.darkColorScheme
+import androidx.compose.material3.lightColorScheme
+import androidx.compose.material3.MaterialTheme
+
+private val KindleLight = lightColorScheme(
+    primary        = KindleColors.Orange,
+    onPrimary      = KindleColors.Black,
+    background      = KindleColors.ChromeCanvas,
+    onBackground    = KindleColors.TextPrimary,
+    surface        = KindleColors.ChromeCanvas,
+    onSurface      = KindleColors.TextPrimary,
+    surfaceVariant = KindleColors.SurfaceSubtle,
+    outline        = KindleColors.Divider,
+    error          = KindleColors.Error,
+)
+
+private val KindleDark = darkColorScheme(
+    primary        = KindleColors.Orange,        // accent unchanged across modes
+    onPrimary      = KindleColors.Black,
+    background      = KindleColors.DarkCanvas,
+    onBackground    = KindleColors.DarkTextPrimary,
+    surface        = KindleColors.DarkSurface1,
+    onSurface      = KindleColors.DarkTextPrimary,
+    surfaceVariant = KindleColors.DarkSurface2,
+    outline        = KindleColors.DarkDivider,
+    error          = KindleColors.Error,
+)
+
+@Composable
+fun KindleChromeTheme(
+    dark: Boolean = isSystemInDarkTheme(),
+    content: @Composable () -> Unit,
+) = MaterialTheme(
+    colorScheme = if (dark) KindleDark else KindleLight,
+    typography = KindleTypography,
+    content = content,
+)
+```
+
+## 2. Typography (Material 3)
+
+Kindle uses a reading serif (**Bookerly**; ship **Bitter** as a free SIL OFL analog) for book text and **Amazon Ember** for chrome (fall back to the system sans for non-Amazon builds). The reading face/size/spacing/margins are user controls.
+
+```kotlin
+// ui/theme/KindleType.kt
+import androidx.compose.material3.Typography
+import androidx.compose.ui.text.TextStyle
+import androidx.compose.ui.text.font.Font
+import androidx.compose.ui.text.font.FontFamily
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.sp
+
+val Bitter = FontFamily(
+    Font(R.font.bitter_regular, FontWeight.Normal),
+    Font(R.font.bitter_bold,    FontWeight.Bold),
+)
+// Amazon Ember requires Amazon's license — for non-Amazon builds use FontFamily.SansSerif
+val Ember = FontFamily(
+    Font(R.font.amazon_ember_regular, FontWeight.Normal),
+    Font(R.font.amazon_ember_medium,  FontWeight.Medium),
+    Font(R.font.amazon_ember_bold,    FontWeight.Bold),
+)
+
+object KindleText {
+    val ScreenTitle  = TextStyle(Ember,  fontWeight = FontWeight.Bold,   fontSize = 30.sp, lineHeight = 36.sp, letterSpacing = (-0.4).sp)
+    val ChapterTitle = TextStyle(Bitter, fontWeight = FontWeight.Bold,   fontSize = 24.sp, lineHeight = 30.sp)
+    val BookTitle    = TextStyle(Ember,  fontWeight = FontWeight.Bold,   fontSize = 20.sp, lineHeight = 26.sp)
+    val Subtitle     = TextStyle(Ember,  fontWeight = FontWeight.Medium, fontSize = 17.sp, lineHeight = 24.sp)
+    val ListTitle    = TextStyle(Ember,  fontWeight = FontWeight.Medium, fontSize = 15.sp, lineHeight = 21.sp)
+    val Meta         = TextStyle(Ember,  fontWeight = FontWeight.Normal, fontSize = 14.sp, lineHeight = 19.sp)
+    val Caption      = TextStyle(Ember,  fontWeight = FontWeight.Medium, fontSize = 12.sp, lineHeight = 16.sp)
+    val Eyebrow      = TextStyle(Ember,  fontWeight = FontWeight.Bold,   fontSize = 11.sp, lineHeight = 13.sp, letterSpacing = 1.5.sp)
+    val Tab          = TextStyle(Ember,  fontWeight = FontWeight.Medium, fontSize = 10.sp, lineHeight = 12.sp, letterSpacing = 0.1.sp)
+    val Note         = TextStyle(Ember,  fontWeight = FontWeight.Normal, fontSize = 13.sp, lineHeight = 20.sp)
+    // Reading body is built dynamically from user settings (see ReadingPage)
+}
+
+val KindleTypography = Typography(
+    headlineLarge  = KindleText.ScreenTitle,
+    headlineMedium = KindleText.BookTitle,
+    titleMedium    = KindleText.ListTitle,
+    bodyMedium     = KindleText.Note,
+    labelSmall     = KindleText.Tab,
+)
+
+// User reading settings (hoist to a DataStore-backed state)
+data class ReadingSettings(
+    val fontFamily: FontFamily = Bitter,
+    val size: Int = 16,                 // sp
+    val lineHeightMultiple: Float = 1.72f,
+    val margin: Int = 26,               // dp — Narrow 16 / Standard 26 / Wide 40
+    val theme: KindleReadingTheme = KindleReadingTheme.Sepia,
+)
+```
+
+## 3. Signature Components
+
+### Reading Page
+
+```kotlin
+import androidx.compose.foundation.background
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.interaction.MutableInteractionSource
+import androidx.compose.foundation.layout.*
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material3.Text
+import androidx.compose.runtime.*
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
+
+@Composable
+fun ReadingPage(
+    chapter: String,
+    title: String,
+    paragraphs: List<String>,
+    percent: Int,
+    minsLeft: Int,
+    settings: ReadingSettings,
+    onToggleChrome: () -> Unit,
+) {
+    val t = settings.theme
+    Box(
+        Modifier
+            .fillMaxSize()
+            .background(t.page)
+            .clickable(indication = null, interactionSource = remember { MutableInteractionSource() }) { onToggleChrome() }
+    ) {
+        Column(
+            Modifier
+                .fillMaxSize()
+                .verticalScroll(rememberScrollState())
+                .padding(horizontal = settings.margin.dp, vertical = 20.dp)
+        ) {
+            Text(chapter, style = KindleText.Eyebrow, color = t.ink.copy(alpha = 0.55f))
+            Spacer(Modifier.height(14.dp))
+            Text(title, style = KindleText.ChapterTitle, color = t.ink)
+            Spacer(Modifier.height(22.dp))
+            paragraphs.forEach { p ->
+                Text(
+                    p,
+                    style = TextStyle(
+                        fontFamily = settings.fontFamily,
+                        fontSize = settings.size.sp,
+                        lineHeight = (settings.size * settings.lineHeightMultiple).sp,
+                        color = t.ink,
+                        textAlign = TextAlign.Justify,   // Compose supports Justify; see note
+                    ),
+                    modifier = Modifier.padding(bottom = 16.dp),
+                )
+            }
+        }
+        // footer whisper + 2dp orange progress hairline
+        Column(Modifier.align(Alignment.BottomStart).padding(horizontal = 24.dp).padding(bottom = 14.dp)) {
+            Box(Modifier.fillMaxWidth().height(2.dp).background(t.ink.copy(alpha = 0.18f))) {
+                Box(Modifier.fillMaxWidth(percent / 100f).fillMaxHeight().background(KindleColors.Orange))
+            }
+            Spacer(Modifier.height(8.dp))
+            Row(Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.SpaceBetween) {
+                Text("$percent%", style = KindleText.Eyebrow, color = t.ink.copy(alpha = 0.55f))
+                Text("$minsLeft min left in chapter", style = KindleText.Eyebrow, color = t.ink.copy(alpha = 0.55f))
+            }
+        }
+    }
+}
+// NOTE: TextAlign.Justify justifies but does not hyphenate. For Kindle-grade
+// justified + hyphenated pagination, use a TextKit-style paginator (e.g. an
+// AndroidView over StaticLayout with Layout.HYPHENATION_FREQUENCY_FULL) or a WebView paginator.
+```
+
+### Aa Typography Panel
+
+```kotlin
+import androidx.compose.foundation.border
+import androidx.compose.foundation.shape.CircleShape
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material3.Slider
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.hapticfeedback.HapticFeedbackType
+import androidx.compose.ui.platform.LocalHapticFeedback
+
+@Composable
+fun AaPanel(settings: ReadingSettings, onChange: (ReadingSettings) -> Unit) {
+    val t = settings.theme
+    val haptics = LocalHapticFeedback.current
+    Column(
+        Modifier
+            .clip(RoundedCornerShape(topStart = 12.dp, topEnd = 12.dp))
+            .background(t.page)
+            .padding(20.dp)
+    ) {
+        Row(verticalAlignment = Alignment.CenterVertically, horizontalArrangement = Arrangement.spacedBy(10.dp)) {
+            Text("Aa", style = KindleText.ChapterTitle.copy(fontSize = 14.sp), color = t.ink)
+            Slider(
+                value = settings.size.toFloat(), valueRange = 12f..26f, steps = 27,
+                onValueChange = { onChange(settings.copy(size = it.toInt())) },
+                modifier = Modifier.weight(1f),
+            )
+            Text("Aa", style = KindleText.ChapterTitle, color = t.ink)
+        }
+        Spacer(Modifier.height(14.dp))
+        Row(horizontalArrangement = Arrangement.spacedBy(12.dp)) {
+            KindleReadingTheme.entries.forEach { theme ->
+                val active = settings.theme == theme
+                Box(contentAlignment = Alignment.Center) {
+                    if (active) {
+                        Box(Modifier.size(38.dp).border(2.dp, KindleColors.Orange, CircleShape))
+                    }
+                    Box(
+                        Modifier
+                            .size(30.dp).clip(CircleShape).background(theme.page)
+                            .border(1.dp, Color.Black.copy(alpha = 0.18f), CircleShape)
+                            .clickable {
+                                onChange(settings.copy(theme = theme))
+                                haptics.performHapticFeedback(HapticFeedbackType.LongPress)
+                            }
+                    )
+                }
+            }
+        }
+    }
+}
+```
+
+### Library Cover Cell
+
+```kotlin
+import androidx.compose.ui.draw.shadow
+import androidx.compose.ui.layout.ContentScale
+import coil.compose.AsyncImage
+
+@Composable
+fun LibraryCover(imageUrl: String?, progress: Float, author: String) {
+    Column(verticalArrangement = Arrangement.spacedBy(6.dp)) {
+        Box(
+            Modifier
+                .aspectRatio(2f / 3f)
+                .shadow(10.dp, RoundedCornerShape(4.dp), spotColor = Color.Black.copy(alpha = 0.4f))
+                .clip(RoundedCornerShape(4.dp))
+        ) {
+            AsyncImage(model = imageUrl, contentDescription = null,
+                modifier = Modifier.matchParentSize(), contentScale = ContentScale.Crop)
+            Box(Modifier.align(Alignment.BottomStart).fillMaxWidth().height(3.dp)
+                .background(Color.White.copy(alpha = 0.2f))) {
+                Box(Modifier.fillMaxWidth(progress).fillMaxHeight().background(KindleColors.Orange))
+            }
+        }
+        Text(
+            if (progress >= 1f) "Finished · $author" else "${(progress * 100).toInt()}% · $author",
+            style = KindleText.Caption, color = KindleColors.TextSecondary,
+        )
+    }
+}
+```
+
+### Reading Progress Bar
+
+```kotlin
+@Composable
+fun KindleProgress(fraction: Float, caption: String, dark: Boolean = false) {
+    Row(verticalAlignment = Alignment.CenterVertically, horizontalArrangement = Arrangement.spacedBy(12.dp)) {
+        Box(
+            Modifier.weight(1f).height(4.dp).clip(RoundedCornerShape(2.dp))
+                .background(if (dark) KindleColors.DarkSurface2 else KindleColors.Divider)
+        ) {
+            Box(Modifier.fillMaxWidth(fraction).fillMaxHeight().background(KindleColors.Orange))
+        }
+        Text(caption, style = KindleText.Caption, modifier = Modifier.width(96.dp))
+    }
+}
+```
+
+## 4. Navigation
+
+Kindle's chrome has a 4-tab bottom strip and a serif large title. On Android, model the strip as a `NavigationBar` (no tint pill — active is the one orange) and the reader top bar as a fade-controlled overlay.
+
+```kotlin
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.*
+import androidx.compose.material3.NavigationBar
+import androidx.compose.material3.NavigationBarItem
+import androidx.compose.material3.NavigationBarItemDefaults
+
+@Composable
+fun KindleBottomBar(selected: Int, onSelect: (Int) -> Unit, dark: Boolean = false) {
+    NavigationBar(
+        containerColor = if (dark) KindleColors.DarkCanvas else KindleColors.ChromeCanvas,
+        tonalElevation = 0.dp,
+    ) {
+        val items = listOf(
+            "Home" to Icons.Filled.Home,
+            "Library" to Icons.Filled.MenuBook,
+            "Discover" to Icons.Filled.Search,
+            "More" to Icons.Filled.MoreHoriz,
+        )
+        items.forEachIndexed { i, (label, icon) ->
+            NavigationBarItem(
+                selected = selected == i,
+                onClick = { onSelect(i) },
+                icon = { Icon(icon, contentDescription = label, modifier = Modifier.size(22.dp)) },
+                label = { Text(label, style = KindleText.Tab) },
+                colors = NavigationBarItemDefaults.colors(
+                    selectedIconColor = KindleColors.Orange,
+                    selectedTextColor = KindleColors.Orange,
+                    unselectedIconColor = if (dark) KindleColors.DarkTextSecondary else KindleColors.TextSecondary,
+                    unselectedTextColor = if (dark) KindleColors.DarkTextSecondary else KindleColors.TextSecondary,
+                    indicatorColor = Color.Transparent, // no Material pill — Kindle has none
+                ),
+            )
+        }
+    }
+}
+```
+
+The Aa panel, X-Ray, and in-book search are `ModalBottomSheet`s (12.dp top radius), Aa panel tinted to the active reading theme. On Dark/Black themes give sheets a 1.dp theme-divider border since shadows are invisible there.
+
+## 5. Motion
+
+Kindle motion is quiet and fast — the reading surface barely moves.
+
+| Moment | Compose recipe |
+|--------|----------------|
+| Chrome fade on book open / center-tap | `AnimatedVisibility(fadeIn(tween(200)), fadeOut(tween(250)))` over nav + tab |
+| Theme swatch select | ring `animateFloatAsState` 1→1.15→1 `spring`; page `animateColorAsState(tween(150))`; `HapticFeedbackType.LongPress` |
+| Library progress fill | `animateFloatAsState(progress, tween(500))` on first composition |
+| Continue-reading cover | scale `animateFloatAsState(1f, tween(250))` from 0.96 |
+| Highlight commit | selected range background `animateColorAsState(tween(120))`; soft haptic |
+| Page turn | horizontal `AnimatedContent` slide `tween(220)`, or a `HorizontalPager`; curl via custom `graphicsLayer` |
+| Sync banner | `AnimatedVisibility(slideInVertically + fadeIn, tween(250))` non-modal |
+
+```kotlin
+// Theme cross-fade — the canonical Kindle reading-surface motion
+val page by animateColorAsState(settings.theme.page, tween(150), label = "page")
+val ink  by animateColorAsState(settings.theme.ink,  tween(150), label = "ink")
+```
+
+Haptics: `LocalHapticFeedback.performHapticFeedback(HapticFeedbackType.LongPress)` for the soft impact on theme select and highlight commit. Page turn has **no** haptic by default. Sync ("furthest page read") is a non-modal banner, no haptic.
+
+## 6. Icons
+
+Kindle's chrome iconography is conventional; the closest first-party set is `androidx.compose.material:material-icons-extended`. The Aa control is text, not an icon; theme swatches are colored circles.
+
+| Purpose | SF Symbol (iOS) | Material Icon (Compose) |
+|---------|-----------------|--------------------------|
+| Home (tab) | `house` / `house.fill` | `Icons.Filled.Home` |
+| Library (tab) | `books.vertical` | `Icons.Filled.MenuBook` |
+| Discover (tab) | `magnifyingglass` | `Icons.Filled.Search` |
+| More (tab) | `ellipsis` | `Icons.Filled.MoreHoriz` |
+| Back to library | `chevron.left` | `Icons.AutoMirrored.Filled.ArrowBack` |
+| Aa panel | (text "Aa") | (text "Aa") |
+| Brightness | `sun.max` | `Icons.Filled.LightMode` |
+| Bookmark | `bookmark` / `bookmark.fill` | `Icons.Filled.BookmarkBorder` / `Icons.Filled.Bookmark` |
+| Search in book | `magnifyingglass` | `Icons.Filled.Search` |
+| Contents / Go To | `list.bullet` | `Icons.AutoMirrored.Filled.List` |
+| X-Ray | `person.text.rectangle` | `Icons.Filled.People` |
+| Sync furthest | `arrow.triangle.2.circlepath` | `Icons.Filled.Sync` |
+| Downloaded | `checkmark.circle.fill` | `Icons.Filled.CheckCircle` |
+| Not downloaded | `arrow.down.circle` | `Icons.Filled.CloudDownload` |
+| Highlight | `highlighter` | `Icons.Filled.BorderColor` |
+| Note | `note.text` | `Icons.Filled.EditNote` |
+| Dictionary / Lookup | `character.book.closed` | `Icons.Filled.Book` |
+| Translate | `globe` | `Icons.Filled.Translate` |
+| Share | `square.and.arrow.up` | `Icons.Filled.IosShare` |
+
+## 7. Minimum SDK & Accessibility Notes
+
+- **minSdk 24** (Compose floor 21; modern motion comfortable at 24). `compileSdk 34+`, Compose BOM `2024.09+`, Kotlin `2.0+`.
+- **Edge-to-edge**: call `enableEdgeToEdge()`. In the reader, set system bars to match the active reading theme (dark icons on White/Sepia/Green, light on Dark/Black) and hide them while chrome is hidden.
+- **Justified reading body**: `TextAlign.Justify` justifies but won't hyphenate — for Kindle-grade pagination use an `AndroidView` over `StaticLayout` with `Layout.HYPHENATION_FREQUENCY_FULL` and `JustificationMode.INTER_WORD`, or a WebView paginator.
+- **Two surface contexts**: the `ReadingPage` renders the user's `KindleReadingTheme` and must NOT read the Material scheme; app chrome uses `isSystemInDarkTheme()`. Keep them decoupled.
+- **Black theme ink**: `#C8C8C8`, never white — reduces halation.
+- **Font scaling**: chrome `sp` honors the user's font scale (titles, list rows, captions). The reading body uses the **in-app** size control; honor system scale only when "Match system size" is on. Pin layout-sensitive chrome (10sp tab labels, eyebrow, footer whisper) by deriving from `dp`.
+- **TalkBack**: expose reading paragraphs as ordered accessible text; the footer whisper as "38 percent, 14 minutes left in chapter"; theme swatches as "Sepia theme, selected"; give every `LibraryCover` a `contentDescription` of "{title} by {author}, {percent}% read"; provide explicit Next/Previous-page custom actions in addition to tap zones.
+- **Touch targets**: Material guidance is 48.dp — give the 30.dp theme swatches and 22.dp tab glyphs a 48.dp hit area; page-turn zones span the page thirds.
+- **Contrast**: every reading theme's ink/page pair is tuned to pass WCAG AA at reading size; the Black theme intentionally trades pure-white contrast for reduced halation.
+- **Reduce motion**: when `Settings.Global.ANIMATOR_DURATION_SCALE == 0`, make the chrome fade instant, drop the theme ring pop and progress fill — keep the state changes; substitute `Crossfade` for page turns.
+- **Dark mode**: app chrome inverts via the `Dark*` palette (`#0E0E0E` canvas, `#1A1A1A` surfaces); the orange `#FF9900` accent is constant in every theme and every mode. Do **not** enable Material You `dynamicColorScheme()` — Kindle's neutral chrome + single orange accent and the user-chosen reading themes must hold regardless of wallpaper.