designmd-forge 1.2.0

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

@@ -0,0 +1,456 @@
+# Obsidian (iOS) — Jetpack Compose Implementation Guide
+
+Companion to [DESIGN.md](DESIGN.md) — the framework-neutral spec. This file ports Obsidian's visual language to **Android with Jetpack Compose (Material 3)**: a color token object, a `Typography` set, paste-ready `@Composable`s, `Modifier`s, 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 (Obsidian's charcoal workshop, single-purple connective accent, the graph view, backlinks pane, dual sans/mono type) while making everything idiomatic Android — a `ModalNavigationDrawer` instead of a slide-over pane, a Compose `Canvas` graph, `sp`/`dp` instead of `pt`.
+
+Assumes Compose BOM `2024.09+`, Kotlin `2.0+`, `minSdk 24`, Material 3, and `androidx.compose.material:material-icons-extended`.
+
+## 1. Color Tokens
+
+```kotlin
+// ui/theme/ObsidianColors.kt
+import androidx.compose.ui.graphics.Color
+
+object ObsidianColors {
+    // Canvas & Surfaces
+    val Canvas   = Color(0xFF1E1E1E)
+    val Surface1 = Color(0xFF262626)
+    val Surface2 = Color(0xFF2D2D2D)
+    val Surface3 = Color(0xFF363636)
+    val Divider  = Color(0xFF363636)
+
+    // Text
+    val TextPrimary   = Color(0xFFDCDDDE)
+    val TextSecondary = Color(0xFF999999)
+    val TextTertiary  = Color(0xFF6B6B6B)
+
+    // Brand
+    val Purple        = Color(0xFF7C3AED)
+    val PurpleLink    = Color(0xFFA78BFA)
+    val PurplePressed = Color(0xFF6D28D9)
+    val PurpleTint    = Color(0x247C3AED) // ~14% alpha
+
+    // Editor & Semantic
+    val ExternalLink = Color(0xFF7C9CBF)
+    val Success      = Color(0xFF4ADE80)
+    val Error        = Color(0xFFF87171)
+    val Highlight    = Color(0x40FFD54F) // ~25% alpha
+}
+```
+
+Wire it into a Material 3 `darkColorScheme` so ripples and stock components inherit the brand. Obsidian is dark-first; a light theme is optional.
+
+```kotlin
+// ui/theme/Theme.kt
+import androidx.compose.material3.darkColorScheme
+import androidx.compose.material3.MaterialTheme
+
+private val ObsidianScheme = darkColorScheme(
+    primary        = ObsidianColors.Purple,
+    onPrimary      = Color.White,
+    background      = ObsidianColors.Canvas,
+    onBackground    = ObsidianColors.TextPrimary,
+    surface         = ObsidianColors.Surface1,
+    onSurface       = ObsidianColors.TextPrimary,
+    surfaceVariant  = ObsidianColors.Surface2,
+    outline         = ObsidianColors.Divider,
+    error           = ObsidianColors.Error,
+)
+
+@Composable
+fun ObsidianTheme(content: @Composable () -> Unit) =
+    MaterialTheme(colorScheme = ObsidianScheme, typography = ObsidianTypography, content = content)
+```
+
+## 2. Typography
+
+Obsidian uses a dual system: Inter for chrome/reading, JetBrains Mono for source/commands. Drop both in `res/font/` (lowercase, snake_case).
+
+```kotlin
+// ui/theme/ObsidianType.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 Inter = FontFamily(
+    Font(R.font.inter_regular,  FontWeight.Normal),   // 400
+    Font(R.font.inter_semibold, FontWeight.SemiBold), // 600
+    Font(R.font.inter_bold,     FontWeight.Bold),     // 700
+)
+val JBMono = FontFamily(
+    Font(R.font.jetbrains_mono_regular,  FontWeight.Normal),   // 400
+    Font(R.font.jetbrains_mono_semibold, FontWeight.SemiBold),  // 600
+)
+
+// Named ramp — mirrors DESIGN.md §3 exactly (pt → sp 1:1)
+object ObsidianText {
+    val NoteTitle    = TextStyle(Inter,  fontWeight = FontWeight.Bold,     fontSize = 26.sp, lineHeight = 33.sp, letterSpacing = (-0.3).sp)
+    val H1           = TextStyle(Inter,  fontWeight = FontWeight.Bold,     fontSize = 24.sp, lineHeight = 31.sp, letterSpacing = (-0.2).sp)
+    val H2           = TextStyle(Inter,  fontWeight = FontWeight.Bold,     fontSize = 20.sp, lineHeight = 26.sp, letterSpacing = (-0.2).sp)
+    val H3           = TextStyle(Inter,  fontWeight = FontWeight.SemiBold, fontSize = 17.sp, lineHeight = 22.sp, letterSpacing = (-0.1).sp)
+    val Reading      = TextStyle(Inter,  fontWeight = FontWeight.Normal,   fontSize = 16.sp, lineHeight = 26.sp)
+    val FileRow      = TextStyle(Inter,  fontWeight = FontWeight.Normal,   fontSize = 15.sp, lineHeight = 20.sp, letterSpacing = (-0.1).sp)
+    val PaneTitle    = TextStyle(Inter,  fontWeight = FontWeight.Bold,     fontSize = 11.sp, lineHeight = 13.sp, letterSpacing = 0.6.sp)
+    val Backlink     = TextStyle(Inter,  fontWeight = FontWeight.Normal,   fontSize = 13.sp, lineHeight = 19.sp)
+    val Metadata     = TextStyle(Inter,  fontWeight = FontWeight.Normal,   fontSize = 13.sp, lineHeight = 17.sp)
+    val TagPill      = TextStyle(Inter,  fontWeight = FontWeight.SemiBold, fontSize = 13.sp, lineHeight = 13.sp)
+    val Button       = TextStyle(Inter,  fontWeight = FontWeight.SemiBold, fontSize = 15.sp, lineHeight = 15.sp, letterSpacing = (-0.1).sp)
+    val NodeLabel    = TextStyle(Inter,  fontWeight = FontWeight.SemiBold, fontSize = 11.sp, lineHeight = 13.sp)
+    val Source       = TextStyle(JBMono, fontWeight = FontWeight.Normal,   fontSize = 15.sp, lineHeight = 23.sp)
+    val CommandRow   = TextStyle(JBMono, fontWeight = FontWeight.Normal,   fontSize = 14.sp, lineHeight = 18.sp)
+    val CommandShort = TextStyle(JBMono, fontWeight = FontWeight.SemiBold, fontSize = 12.sp, lineHeight = 12.sp)
+}
+
+// Map onto Material 3 slots so stock components inherit the brand
+val ObsidianTypography = Typography(
+    headlineLarge = ObsidianText.NoteTitle,
+    headlineMedium = ObsidianText.H1,
+    headlineSmall = ObsidianText.H2,
+    titleMedium   = ObsidianText.H3,
+    bodyMedium    = ObsidianText.Reading,
+    labelSmall    = ObsidianText.PaneTitle,
+)
+```
+
+## 3. Signature Components
+
+### File-Tree Row (the navigation unit)
+
+```kotlin
+@Composable
+fun FileTreeRow(
+    name: String,
+    depth: Int,
+    isFolder: Boolean = false,
+    expanded: Boolean = false,
+    isActive: Boolean = false,
+    isModified: Boolean = false,
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+) {
+    val interaction = remember { MutableInteractionSource() }
+    val pressed by interaction.collectIsPressedAsState()
+    val rot by animateFloatAsState(if (expanded) 90f else 0f, tween(180), label = "chev")
+    val bg = when {
+        isActive -> ObsidianColors.PurpleTint
+        pressed  -> ObsidianColors.Surface2
+        else     -> Color.Transparent
+    }
+
+    Box {
+        Row(
+            modifier = modifier
+                .fillMaxWidth()
+                .height(32.dp)
+                .background(bg)
+                .clickable(interaction, indication = null, onClick = onClick)
+                .padding(horizontal = 12.dp),
+            verticalAlignment = Alignment.CenterVertically,
+            horizontalArrangement = Arrangement.spacedBy(6.dp),
+        ) {
+            Spacer(Modifier.width((depth * 16).dp))
+            if (isFolder) {
+                Icon(Icons.Filled.ChevronRight, null, tint = ObsidianColors.TextSecondary,
+                    modifier = Modifier.size(10.dp).graphicsLayer { rotationZ = rot })
+            } else Spacer(Modifier.width(10.dp))
+            Icon(
+                if (isFolder) Icons.Filled.Folder else Icons.Filled.Description,
+                null,
+                tint = if (isActive) ObsidianColors.PurpleLink else ObsidianColors.TextSecondary,
+                modifier = Modifier.size(14.dp),
+            )
+            Text(name, style = ObsidianText.FileRow, color = ObsidianColors.TextPrimary,
+                maxLines = 1, overflow = TextOverflow.Ellipsis, modifier = Modifier.weight(1f))
+            if (isModified) Box(Modifier.size(6.dp).clip(CircleShape).background(ObsidianColors.PurpleLink))
+        }
+        if (isActive) Box(Modifier.align(Alignment.CenterStart).width(2.dp).fillMaxHeight().background(ObsidianColors.Purple))
+    }
+}
+```
+
+### Markdown Source Line (dimmed syntax)
+
+```kotlin
+import androidx.compose.ui.text.buildAnnotatedString
+import androidx.compose.ui.text.SpanStyle
+import androidx.compose.ui.text.withStyle
+import androidx.compose.ui.text.style.TextDecoration
+
+enum class TokKind { Syntax, Wikilink, External, Code, Text }
+data class Tok(val kind: TokKind, val text: String)
+
+@Composable
+fun SourceLine(tokens: List<Tok>) {
+    val text = buildAnnotatedString {
+        tokens.forEach { t ->
+            val color = when (t.kind) {
+                TokKind.Syntax   -> ObsidianColors.TextTertiary
+                TokKind.Wikilink -> ObsidianColors.PurpleLink
+                TokKind.External -> ObsidianColors.ExternalLink
+                else             -> ObsidianColors.TextPrimary
+            }
+            withStyle(SpanStyle(color = color,
+                textDecoration = if (t.kind == TokKind.Wikilink) TextDecoration.Underline else null)) {
+                append(t.text)
+            }
+        }
+    }
+    Text(text, style = ObsidianText.Source)
+}
+```
+
+### Tag Pill (a connection, not metadata)
+
+```kotlin
+@Composable
+fun TagPill(tag: String, onClick: () -> Unit) {
+    val interaction = remember { MutableInteractionSource() }
+    val pressed by interaction.collectIsPressedAsState()
+    Box(
+        Modifier
+            .clip(CircleShape)
+            .background(if (pressed) Color(0x3D7C3AED) else ObsidianColors.PurpleTint)
+            .clickable(interaction, indication = null, onClick = onClick)
+            .padding(horizontal = 9.dp, vertical = 3.dp),
+    ) {
+        Text("#$tag", style = ObsidianText.TagPill, color = ObsidianColors.PurpleLink)
+    }
+}
+```
+
+### Graph View (physics-driven nodes)
+
+```kotlin
+import androidx.compose.foundation.Canvas
+import androidx.compose.ui.geometry.Offset
+
+data class GNode(val id: String, var x: Float, var y: Float, val r: Float, val active: Boolean = false)
+data class GEdge(val a: String, val b: String)
+
+@Composable
+fun GraphView(nodesState: List<GNode>, edges: List<GEdge>, modifier: Modifier = Modifier) {
+    // Drive `nodesState` from a force-sim coroutine (edge springs + repulsion + centering),
+    // recomposing ~60fps; here we just render the current frame.
+    Canvas(modifier.fillMaxSize().background(ObsidianColors.Canvas)) {
+        fun at(id: String) = nodesState.first { it.id == id }
+        edges.forEach { e ->
+            val a = at(e.a); val b = at(e.b)
+            val bright = a.active || b.active
+            drawLine(
+                if (bright) ObsidianColors.Purple else ObsidianColors.Divider,
+                Offset(a.x, a.y), Offset(b.x, b.y), strokeWidth = 1f,
+            )
+        }
+        nodesState.forEach { n ->
+            if (n.active) drawCircle(ObsidianColors.PurpleTint, n.r + 8f, Offset(n.x, n.y))
+            drawCircle(if (n.active) ObsidianColors.PurpleLink else ObsidianColors.Purple, n.r, Offset(n.x, n.y))
+        }
+    }
+}
+```
+
+### Command Palette
+
+```kotlin
+@Composable
+fun CommandPalette(rows: List<Pair<String, String>>) {
+    var query by remember { mutableStateOf("") }
+    val focused = 0
+
+    Column(
+        Modifier
+            .widthIn(max = 560.dp)
+            .fillMaxWidth()
+            .clip(RoundedCornerShape(10.dp))
+            .background(ObsidianColors.Surface1)
+            .border(1.dp, ObsidianColors.Divider, RoundedCornerShape(10.dp)),
+    ) {
+        Row(
+            Modifier.height(44.dp).padding(horizontal = 16.dp),
+            verticalAlignment = Alignment.CenterVertically,
+            horizontalArrangement = Arrangement.spacedBy(10.dp),
+        ) {
+            Text(">", style = ObsidianText.CommandRow, color = ObsidianColors.TextTertiary)
+            BasicTextField(
+                value = query, onValueChange = { query = it },
+                singleLine = true,
+                textStyle = ObsidianText.CommandRow.copy(color = ObsidianColors.TextPrimary),
+                cursorBrush = SolidColor(ObsidianColors.PurpleLink),
+                modifier = Modifier.weight(1f),
+                decorationBox = { inner ->
+                    if (query.isEmpty()) Text("Type a command…",
+                        style = ObsidianText.CommandRow, color = ObsidianColors.TextTertiary)
+                    inner()
+                },
+            )
+        }
+        HorizontalDivider(color = ObsidianColors.Divider)
+        LazyColumn {
+            itemsIndexed(rows) { i, (label, shortcut) ->
+                Row(
+                    Modifier
+                        .fillMaxWidth()
+                        .height(38.dp)
+                        .background(if (i == focused) ObsidianColors.PurpleTint else Color.Transparent)
+                        .padding(horizontal = 16.dp),
+                    verticalAlignment = Alignment.CenterVertically,
+                ) {
+                    Text(label, style = ObsidianText.CommandRow, color = ObsidianColors.TextPrimary, modifier = Modifier.weight(1f))
+                    Text(shortcut, style = ObsidianText.CommandShort, color = ObsidianColors.TextSecondary)
+                }
+            }
+        }
+    }
+}
+```
+
+### Backlinks Pane
+
+```kotlin
+@Composable
+fun BacklinksPane(backlinks: List<Pair<String, String>>) {
+    Column(Modifier.background(ObsidianColors.Surface1)) {
+        Row(
+            Modifier.padding(horizontal = 16.dp, vertical = 12.dp),
+            horizontalArrangement = Arrangement.spacedBy(8.dp),
+        ) {
+            Text("LINKED MENTIONS", style = ObsidianText.PaneTitle, color = ObsidianColors.TextSecondary)
+            Text("${backlinks.size}", style = ObsidianText.Metadata, color = ObsidianColors.TextSecondary)
+        }
+        backlinks.forEach { (title, ctx) ->
+            Column(Modifier.padding(horizontal = 16.dp, vertical = 10.dp), verticalArrangement = Arrangement.spacedBy(4.dp)) {
+                Text(title, style = ObsidianText.Button, color = ObsidianColors.TextPrimary)
+                Text(ctx, style = ObsidianText.Backlink, color = ObsidianColors.TextSecondary, maxLines = 2, overflow = TextOverflow.Ellipsis)
+            }
+        }
+    }
+}
+```
+
+### Primary Button
+
+```kotlin
+@Composable
+fun ObsidianPrimaryButton(text: String, onClick: () -> Unit, modifier: Modifier = Modifier) {
+    val interaction = remember { MutableInteractionSource() }
+    val pressed by interaction.collectIsPressedAsState()
+    val scale by animateFloatAsState(if (pressed) 0.98f else 1f,
+        spring(dampingRatio = 0.85f, stiffness = 600f), label = "btnScale")
+    val haptics = LocalHapticFeedback.current
+
+    Box(
+        modifier = modifier
+            .scale(scale)
+            .height(34.dp)
+            .clip(RoundedCornerShape(6.dp))
+            .background(if (pressed) ObsidianColors.PurplePressed else ObsidianColors.Purple)
+            .clickable(interaction, indication = null) {
+                haptics.performHapticFeedback(HapticFeedbackType.LongPress)
+                onClick()
+            }
+            .padding(horizontal = 16.dp),
+        contentAlignment = Alignment.Center,
+    ) {
+        Text(text, style = ObsidianText.Button, color = Color.White)
+    }
+}
+```
+
+## 4. Navigation (no bottom bar) — Ribbon + File-Tree Drawer
+
+Obsidian's iOS app is a left ribbon plus a slide-over file-tree pane with **no bottom navigation**. Use a fixed `Row` ribbon and a Material 3 `ModalNavigationDrawer` for the tree.
+
+```kotlin
+@Composable
+fun ObsidianWorkspace() {
+    val drawerState = rememberDrawerState(DrawerValue.Closed)
+    Row(Modifier.fillMaxSize().background(ObsidianColors.Canvas)) {
+        // Ribbon
+        Column(
+            Modifier.width(40.dp).fillMaxHeight().background(ObsidianColors.Surface1).padding(vertical = 12.dp),
+            horizontalAlignment = Alignment.CenterHorizontally,
+            verticalArrangement = Arrangement.spacedBy(4.dp),
+        ) {
+            listOf(Icons.Filled.BubbleChart, Icons.Filled.Terminal, Icons.Filled.Search, Icons.Filled.EditNote).forEach {
+                Icon(it, null, tint = ObsidianColors.TextSecondary,
+                    modifier = Modifier.size(40.dp).padding(10.dp))
+            }
+            Spacer(Modifier.weight(1f))
+            Icon(Icons.Filled.Settings, null, tint = ObsidianColors.TextSecondary,
+                modifier = Modifier.size(40.dp).padding(10.dp))
+        }
+        ModalNavigationDrawer(
+            drawerState = drawerState,
+            scrimColor = Color.Black.copy(alpha = 0.5f),
+            drawerContent = {
+                ModalDrawerSheet(
+                    drawerContainerColor = ObsidianColors.Surface1,
+                    modifier = Modifier.width(280.dp),
+                ) {
+                    // FileTreeRow(...) entries — the vault explorer
+                }
+            },
+        ) {
+            // Editor + (backlinks / graph) content
+        }
+    }
+}
+```
+
+## 5. Motion
+
+| Moment | Compose recipe |
+|--------|----------------|
+| Command palette open | `AnimatedVisibility` `fadeIn(tween(130))` + `scaleIn(initialScale = 0.97f, tween(130))` |
+| File-tree folder toggle | `AnimatedVisibility` `expandVertically`/`shrinkVertically` `tween(180)` + chevron `rotationZ` |
+| Node focus | `animateColorAsState` brighten + halo `tween(250)` (driven from sim state) |
+| Reading/source toggle | `Crossfade(targetState = readingMode, animationSpec = tween(200))` |
+| Pane slide-over | `ModalNavigationDrawer` default spring, `0.5` scrim |
+| Graph physics | a `LaunchedEffect` fixed-timestep loop integrating velocities ~60fps, settling over ~600ms |
+
+```kotlin
+// Graph force loop sketch
+LaunchedEffect(graphId) {
+    while (isActive) {
+        withFrameNanos { /* repulsion + edge springs + centering → update node offsets */ }
+    }
+}
+```
+
+Haptics: prefer `LocalHapticFeedback`. For a crisper tick matching iOS `.light` impact use `LocalView.current.performHapticFeedback(HapticFeedbackConstants.CONTEXT_CLICK)` (API 30+) on note open, command run, and tag-pill tap.
+
+## 6. Icons
+
+The closest first-party set is `androidx.compose.material:material-icons-extended`.
+
+| Purpose | SF Symbol (iOS) | Material Icon (Compose) |
+|---------|-----------------|--------------------------|
+| File (tree) | `doc.text` | `Icons.Filled.Description` |
+| Folder (tree) | `folder.fill` | `Icons.Filled.Folder` |
+| Folder chevron | `chevron.right` | `Icons.Filled.ChevronRight` |
+| Graph (ribbon) | `circle.hexagongrid` | `Icons.Filled.BubbleChart` |
+| Command palette (ribbon) | `command` | `Icons.Filled.Terminal` |
+| Search (ribbon) | `magnifyingglass` | `Icons.Filled.Search` |
+| New note (ribbon) | `square.and.pencil` | `Icons.Filled.EditNote` |
+| Settings (ribbon) | `gearshape` | `Icons.Filled.Settings` |
+| Reading/source toggle | `book` / `chevron.left.forwardslash.chevron.right` | `Icons.Filled.MenuBook` / `Icons.Filled.Code` |
+| Backlink | `arrow.uturn.backward` | `Icons.AutoMirrored.Filled.Undo` |
+| Tag | `number` | `Icons.Filled.Tag` |
+| Modified dot | `circle.fill` | `Icons.Filled.Circle` |
+| More | `ellipsis` | `Icons.Filled.MoreHoriz` |
+
+## 7. Minimum SDK & Accessibility Notes
+
+- **minSdk 24** (Compose floor is 21; modern motion comfortable at 24). `compileSdk 34+`, Compose BOM `2024.09+`, Kotlin `2.0+`.
+- **Edge-to-edge**: call `enableEdgeToEdge()`; the charcoal canvas wants light-content system bars. Apply `Scaffold` / `Modifier.windowInsetsPadding(WindowInsets.systemBars)` so the editor + keyboard accessory clear the gesture nav.
+- **Two type systems**: keep Inter for chrome/reading and JetBrains Mono for source/commands — verify both render with the bundled fonts.
+- **Font scaling**: `sp` honors the user scale — keep it on reading body / titles / file rows; keep a 13sp floor on the mono source to preserve the grid; pin graph node labels and 12sp command shortcuts (derive from `dp` or wrap in `CompositionLocalProvider(LocalDensity provides Density(density, fontScale = 1f))`).
+- **TalkBack**: the `Canvas` graph is opaque to screen readers — provide a parallel accessible list of nodes ("Note Name, 5 links"); the active node announces "current note"; give wikilinks a link role + label ("Project Plan, internal link"); never rely on the purple color alone.
+- **Touch targets**: Material guidance is 48.dp minimum. The 32.dp file-tree row and 20.dp ribbon glyphs must get a 48.dp hit area via padding/hit-slop.
+- **Contrast**: `#999999` on `#1E1E1E` passes WCAG AA at 13sp+. `#6B6B6B` syntax markers are intentionally low-contrast — fine for decoration, never for essential text.
+- **Reduced motion**: honor the system setting — freeze the graph physics into a static layout and drop the command-palette scale, keeping only the opacity fade.
+- **Dynamic color**: do **not** enable Material You `dynamicDarkColorScheme()` — Obsidian's identity requires the fixed charcoal canvas and single-purple connective accent regardless of wallpaper.