Develop — Wear OS

preview

Wear OS 6 surface contract: EdgeButton (arc-shaped), Primary Layout slot-based, round-display optimization, watch-face color derivation. Spec preview — no Koder product consumes Wear OS today. Companion impl tracker: projects/koder-stack#155. SDK target: koder_kit_wear (futuro).

Spec — Wear OS (Develop)

*tatus: preview*(20260514). Não há produto Koder pra Wear hoje. Esta spec serve como contrato pra futura implementação. Impl tracker: projects/koder-stack#155 (dormente).

Princípios

  1. *ound-display optimization*— assume round display by default; safe area = inscribed square.
  2. *lot-based layouts*— fixed slots (titlemainbottom); custom layouts discouraged.
  3. *dgeButton paradigm*— arc-shaped buttons hugging the perimeter.
  4. *olor derives from watch face*— tile color reflects active face; user customization respected.
  5. *attery aware*— animations minimal; no auto-running motion.

R1 — EdgeButton

Arc-shaped button hugging the perimeter of round display:

Token Diameter (round display) Use
sm 36dp arc Compact action
md 48dp arc Default
lg 56dp arc Hero (primary action)
xl 64dp arc Critical/destructive

Anchor positions:

Position Arc orientation
Top Top-center arc, opening down
Bottom Bottom-center arc, opening up
Left Left-side arc, opening right (LTR)
Right Right-side arc, opening left (LTR)

Multi-EdgeButton: max 2 simultaneous (typically top + bottom OR left + right).

Shape morph: pressed state → arc thickens (1.5× width) via motion-spatial-fast; release → spring back.

R2 — Primary Layout (slot-based)

   ┌────────────────────┐
   │     [titleSlot]    │   ← top arc area
   ├────────────────────┤
   │                    │
   │     [mainSlot]     │   ← center square area (safe)
   │                    │
   ├────────────────────┤
   │   [bottomSlot]     │   ← bottom arc area
   └────────────────────┘

Slots:

Slot Content Anchor
*itleSlot* Title text OR small icon Top arc; max 1 line
*ainSlot* Primary content (list, scroll, animation) Center square (inscribed in round display)
*ottomSlot* EdgeButton OR navigation hint Bottom arc

Custom layouts discouraged — slot pattern ensures consistent safe area + battery efficiency.

R3 — Round-display optimization

  • *afe area*= largest inscribed square inside round display. Content MUST fit within.
  • *dge masking*— content beyond square auto-masked by display geometry.
  • *nchor patterns*
    • Text: centeraligned only (NOT corneranchored — corners obscured).
    • Lists: vertical scroll, snap to integer multiples of item height; first item top of square area.

For square Wear displays (rare; legacy): same patterns work — square IS the safe area.

R4 — Color derivation from watch face

Active watch face exposes 3 colors via API (getWatchFaceColors() Jetpack):

Color Mapping to Koder roles
Primary watch face color primary
Secondary watch face color secondary
Accent watch face color accent

App can OPT-OUT of derivation: declare watchFaceColorDerivation: false in koder.toml → uses preset defaults.

Surfaces refresh on watch-face change (system event).

R5 — Distribution

Channel Notes
Play Store Wear OS tab Primary distribution
Koder Hub hub.koder.dev/apps/<slug>?platform=wear Sideload

App size budget: < 30MB compressed (Wear OS recommendation).

R6 — Surface bindings

Surface API
Koder Wear SDK koder_kit_wear package (futuro) — wraps androidx.wear.compose.material3
Compose Wear OS Underlying API (androidx.wear.compose.material3)
Watch face APIs Jetpack Wear watchface library

Koder Wear apps are Compose-only (no Flutter for Wear — Flutter doesn't target Wear officially).

R7 — Acessibilidade

  • Touch target: ≥ 28dp (Wear baseline; smaller than 48dp mobile per OS guidelines).
  • Screen reader: TalkBack Wear OS support per slot.
  • Reducedmotion: ALL animations disabled (battery + motionsickness).
  • Haptic feedback: light tactile per tap (per Wear OS pattern).

R8 — i18n

Key en-US pt-BR
wear.app.title.fallback "{app}" "{app}"
wear.edge_button.back "Back" "Voltar"

R9 — Per-preset variation

Preset Wear OS appearance
material3 / material_expressive Defaults (color derivation + slots)
material2 Color derivation OFF; flat slots
terminal_classic n/a (Wear não roda terminal)
brutalist Sharp EdgeButtons (no shape morph)
cyberpunk_neon Default + glow on EdgeButton press
minimalist_mono Single-color text only; no slot dividers

T-suite

  • *1*EdgeButton smmdlg/xl render with correct arc width per R1.
  • *2*Primary Layout: titleSlot + mainSlot + bottomSlot present with content; safe area inscribed in round display.
  • *3*Watch face color derivation: simulate face color change → app colors update.
  • *4*Opt-out: watchFaceColorDerivation: false → preset defaults used.
  • *5*Reducedmotion: animations disabled (battery + motionsickness).
  • *6*App size < 30MB compressed.
  • *7*TalkBack Wear: slot navigation order correct.

R10 — Status preview / future

This spec is *review*until:

  1. Koder product targets Wear OS officially.
  2. koder_kit_wear SDK scaffold exists.
  3. At least 1 implementation reference (e.g., Koru timer/focus on Wear).

Until then: spec ratified as contract; impl tracker projects/koder-stack#155 dormant.

  • Sibling: android-compose.kmd (Compose base; Wear builds on)
  • Shape: ../themes/shape-library.kmd (EdgeButton arc shapes)
  • Motion: ../themes/motion.kmd (batteryaware reducedmotion default)
  • Impl tracker: projects/koder-stack/backlog/pending/155-wear-os-surface-and-koder-kit-wear.md
  • Refs: Wear OS 6 design guidelines; androidx.wear.compose.material3

Source: ../home/koder/dev/koder/meta/docs/stack/specs/develop/wear-os.kmd