linkding-ios/docs/design-wwdc26.md

# Marks — WWDC26 Design Brief

Source: WWDC26 session transcripts (`~/master/scratch/claude-setup/wwdc26/transcripts`).
Sessions digested: Principles of Great Design, Communicate Your Brand Identity on iOS,
What's New in SwiftUI, Dive into Lazy Stacks and Scrolling, Compose Advanced Graphics
Effects, Design Intuitive Search Experiences, WidgetKit Foundations, Create UI Prototypes
Using Agents in Xcode.

Everything below is mapped to Marks (SwiftUI bookmarks / read-later app, iOS 26 target,
with a home-screen widget and a share extension).

---

## The mental model: two layers (iOS 26 Liquid Glass)

- **UI layer** — tab bar, toolbars, search field → keep **native**. Don't restyle them.
- **Content layer** — the bookmark rows → **this is the canvas.** All editorial brand lives here.

The editorial-row direction is correct: it's the sanctioned place for personality. Corollary:
**move any header/brand color into the scroll content**, not onto the toolbar. The Liquid Glass
bar then picks up the tint dynamically as rows scroll under it, and content goes edge-to-edge
instead of being letterboxed by a colored bar.

> "Think of your app as two distinct layers: the UI layer … and the content layer … the content
> layer is the best opportunity to express your brand identity."

---

## Bookmark list (highest leverage)

- **Row hierarchy** answers three questions at a glance: *what do I look at, what can I tap, how?*
  Title most prominent; favicon + domain + reading-time/date as the "context that makes it
  simpler" (a bare title is *less* usable, not more). Build hierarchy with **order, spacing,
  contrast** — not by stripping.
- **No truncation under Dynamic Type — wrap to multiple lines.** Mandatory to test if shipping
  any custom font (free only with system fonts). New York (system serif) gives an editorial feel
  with Dynamic Type for free.
- **Swipe actions = forgiveness, not confirmation.** Undo over alerts; consistent positions;
  standard metaphors only (no creative-liberty trash/archive icons).
- **Tint = meaning only:** unread/synced status, selection, primary save. Everything else neutral.
- **Wordmark only on the main list, fade on scroll** (NYT Cooking pattern). "People don't need to
  be reminded which app they're using."

> "When your hierarchy is strong, the most important item on the screen is always the most obvious one."

---

## SwiftUI wins (two are nearly free on iOS 26 once built with Xcode 27)

1. **`AsyncImage` now HTTP-caches by default** → favicons/thumbnails survive scroll-away/back.
   Biggest free win for an image-heavy list. Add a sized `URLCache` via `.asyncImageURLSession(_:)`
   if loading many.
2. **`@State` is now a lazy macro** → row/view models stop re-allocating on every parent update
   (back-ports to iOS 17+). *One source-break to grep for:* a `@State` var with both a default
   value **and** an `init` assignment now errors.
3. `toolbarMinimizeBehavior(.onScrollDown, for: .navigationBar)` to reclaim reading space.
4. Drag-to-reorder via `reorderable`/`reorderContainer`; swipe actions work outside `List` via
   `swipeActionsContainer` if rows move to `LazyVStack`.

### Scroll-perf traps that bite editorial lists specifically

- **Don't put conditional/dynamic content in `ForEach` leaf rows** (`if env { Row() }`) — keeps
  off-screen rows alive and re-evaluating. **Filter at the data level** (SwiftData `#Predicate`
  on `@Query`).
- **Configure rows in their initializer, not `onAppear`** (and `onAppear` isn't guaranteed in lazy
  stacks — fine for paging, wrong for setup).
- Scroll-driven effects: use **scale/opacity**, never a transform that moves the row's frame, or
  lazy rows vanish early.
- Read **`onScrollTargetVisibilityChange`** (visibility), not content-offset, for
  "jump to top/unread" buttons.

---

## Search

- Put search in the **bottom toolbar** (most reachable; animates up over the keyboard) unless a
  sheet blocks the bottom. `.searchable(text:placement:prompt:)`.
- Add a **scope bar** (`.searchScopes`) for All / Unread / tag; optionally layer **search tokens**
  on top — but pair tokens with the visible scope bar (tokens alone aren't discoverable).
- **`ContentUnavailableView.search(text:)`** for no-results, echoing the query so typos are obvious.

---

## Widget (MarksWidget)

- **`AppIntentConfiguration`** so users pick a tag/collection (1–2 params, sensible default, don't
  force config). Reuse the existing app group (`group.com.magicive.marks`).
- Reload policy **`.never`** + call **`WidgetCenter.shared.reloadTimelines(ofKind:)` when the app
  *and the share extension* background after a save** — content changes on save, not on a clock.
- **`.widgetAccentedRenderingMode(.fullColor)` on favicons/thumbnails** — otherwise they render as
  white rectangles in tinted/clear Home Screen modes. Test full-color / tinted / clear.
- Carry the app's editorial palette for instant recognizability; consider iOS 27's new
  `.systemExtraLargePortrait` for a richer list. Deep-link rows with `.widgetURL`.

---

## Prototyping workflow

The "create UI prototypes with agents in Xcode" flow fits well: ask for *many named SwiftUI
previews* of BookmarkListRow variants against **realistic sample data + edge cases** (long titles,
missing thumbnails, hundreds of rows), then remix the ones you like. Output is real native SwiftUI
you keep. Best targets: BookmarkListRow layouts, the search results + empty states, the row→detail
transition, and the widget's families.

---

## Cross-cutting principles (Principles of Great Design)

- **Agency / forgiveness:** undo over confirmation for destructive actions; only interrupt for
  genuinely big mistakes (bulk delete).
- **Familiarity:** standard symbols/metaphors; things that look the same behave the same.
- **Simplicity = removing friction**, not minimalism. "You'll know you've arrived at simplicity
  when you have exactly enough."
- **Craft = materials:** good fonts, adaptive colors, crisp icons, responsive animation. Watch the
  anti-patterns: jittery scrolling, misaligned icons, layout breaking on rotation, taps with no
  immediate response — these are the trust-killers in a scrolling list.
- **Dark Mode is non-negotiable.**
- **Delight is the result of getting everything else right** — pick the target emotion (calm,
  editorial, focused) and reinforce it everywhere.

---

## Suggested punch-list order

1. `AsyncImage` caching + `.widgetAccentedRenderingMode(.fullColor)` (free correctness/perf).
2. Audit `@State` view models for the lazy-init source-break before bumping SDK.
3. Move search to bottom toolbar + scope bar + `ContentUnavailableView.search`.
4. Row Dynamic Type wrapping audit; confirm no conditional content in `ForEach` leaves.
5. Widget → `AppIntentConfiguration` + `.never` reload + reload-on-save from app & share extension.

---

## Codebase audit (current vs. brief)

### Already compliant
- Native UI layer; brand lives in rows; no toolbar color letterboxing (`BookmarksView.swift`).
- Standard swipe metaphors — trash/archivebox/pencil (`BookmarkListRow.swift`).
- Dark-mode-safe: semantic colors throughout.
- `ContentUnavailableView.search(text:)` already used (`SearchView.swift`).
- Deep links via `Link(destination: .marksBookmark(...))` (`RecentBookmarksWidget.swift`).
- Reload-on-save already wired (`WidgetDataStore.saveBookmarks` → `reloadTimelines`).
- `onAppear` paging — the sanctioned lazy-list use (`BookmarksView.swift`).

### Fixed (this pass)
- **P1 Dynamic Type** — `BookmarkRow` converted from fixed `.system(size:)` points to text
  styles: title `.headline`, domain/date `.footnote`, summary `.subheadline`, tags
  `.caption`, podcast glyph `.title3`. Title already wraps (`lineLimit(2)` + `fixedSize`).
- **P2 disk I/O in `body`** — `podcastCached` was `FileManager.fileExists` evaluated during
  render (per row, per scroll frame). Moved to `@State` populated by a `.task(id: bookmark.url)`
  that stats off the main actor — once per appearance, not per render.
- **P3 unrecoverable delete** — destructive trailing swipe changed to `allowsFullSwipe: false`
  so a single fling no longer deletes instantly; requires tapping the revealed button.

### Still open (optional)
- Favicon `URLCache` sizing via `.asyncImageURLSession(_:)` (iOS 26 already caches by default).
- True **undo** for delete (snackbar + soft-delete) — current fix only removes the accidental
  full-swipe; an explicit tap still deletes immediately.
- Widget fonts still use fixed sizes (left as-is — widgets clamp Dynamic Type; lower value).
- Search scope bar (`.searchScopes`) for All / Unread / tag.
- Widget `AppIntentConfiguration`, more families incl. `.systemExtraLargePortrait`, interactive
  "mark read" `AppIntent`.