Develop — Wear OS

develop specs/develop/wear-os.kmd

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).

When this spec applies

Primary triggers

Add Wear OS support to a Koder product

All triggers

Build Wear OS variant of a Koder product
Define watch-aware component

Spec — Wear OS (Develop)

Status: preview (2026-05-14). 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

Round-display optimization — assume round display by default; safe area = inscribed square.
Slot-based layouts — fixed slots (title/main/bottom); custom layouts discouraged.
EdgeButton paradigm — arc-shaped buttons hugging the perimeter.
Color derives from watch face — tile color reflects active face; user customization respected.
Battery 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
titleSlot	Title text OR small icon	Top arc; max 1 line
mainSlot	Primary content (list, scroll, animation)	Center square (inscribed in round display)
bottomSlot	EdgeButton OR navigation hint	Bottom arc

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

R3 — Round-display optimization

Safe area = largest inscribed square inside round display. Content MUST fit within.
Edge masking — content beyond square auto-masked by display geometry.
Anchor patterns:
- Text: center-aligned only (NOT corner-anchored — 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.
Reduced-motion: ALL animations disabled (battery + motion-sickness).
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

T1 EdgeButton sm/md/lg/xl render with correct arc width per R1.
T2 Primary Layout: titleSlot + mainSlot + bottomSlot present with content; safe area inscribed in round display.
T3 Watch face color derivation: simulate face color change → app colors update.
T4 Opt-out: watchFaceColorDerivation: false → preset defaults used.
T5 Reduced-motion: animations disabled (battery + motion-sickness).
T6 App size < 30MB compressed.
T7 TalkBack Wear: slot navigation order correct.

R10 — Status preview / future

This spec is preview until:

Koder product targets Wear OS officially.
koder_kit_wear SDK scaffold exists.
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.

Cross-link

Sibling: android-compose.kmd (Compose base; Wear builds on)
Shape: ../themes/shape-library.kmd (EdgeButton arc shapes)
Motion: ../themes/motion.kmd (battery-aware reduced-motion 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

References

specs/develop/android-compose.kmd
specs/themes/shape-library.kmd
specs/themes/motion.kmd