Spec — Shape library

Facet Visual do Koder Design. Material parity: https://m3.material.io/styles/shape. Source of polygon paths: androidx.graphics.shapes.

Companion to shape.kmd:

• shape.kmd defines the radius scale (xs/sm/md/lg/xl/full) bound to corners of rectangular surfaces (cards, buttons, sheets).
• shape-library.kmd defines the 35 named polygon shapes used for non-rectangular surfaces (loading indicators, FAB morphs, Hero carousels, expressive decorations).

Both coexist: a Card uses shape.kmd radius tokens; a Loading indicator (#065) uses shape-library.kmd polygon shapes.

R1 — Catalog (35 shapes)

Tier:

• baseline shapes (#1-5) MUST be present in every preset.
• expressive shapes (#6-35) are opt-in per preset; presets that disable Expressive (e.g., terminal_classic, brutalist) MAY declare them as no-ops mapping to Square or Pill.

Source of truth: polygon vertex coordinates and SVG paths come from androidx.graphics.shapes (vendored under engines/sdk/koder-design-compose/shapes/ once #062.G11 ships). Other surfaces (Flutter, SwiftUI, Web) re-export the same vertex data — no per-surface re-derivation.

R2 — Morphing contract

Two named shapes A → B can morph if they share the same number of morph vertices (vertex correspondence map). Where vertex counts differ, the library MUST subdivide the lower-count shape into the higher count before interpolation:

morph(Square, Cookie-12)
  → subdivide(Square) from 4 → 12 vertices (each edge into 3 segments)
  → interpolate(square_12v_i, cookie_12v_i) for i in 0..11
  → output frame

Subdivision is deterministic per androidx.graphics.shapes algorithm — same A,B always yields same intermediate frames.

R2.1 — Required morph pairs

Components that animate shape MUST declare their morph pair in their spec (e.g., loading-indicator.kmd R2 declares Cookie-4 → Burst → Flower → Cookie-4 cycle).

R2.2 — Animation driver

Shape morph MUST be driven by motion.kmd R9.1 spring tokens (spatial). Duration-driven morphs are forbidden because spring overshoot is part of the perceptual signature.

R3 — Surface bindings

For Web, precompute morph frames at build time (e.g., 30 keyframes between A and B) and serve them as a CSS variable lookup table — do NOT compute polygon math at runtime in JS.

R4 — Accessibility

• Shape morph honors prefers-reduced-motion: when set, MUST snap directly to end state (no intermediate frames). Same contract as motion.kmd R6.
• Decorative-only shapes (#14-35 used purely for decoration) MUST carry aria-hidden="true" or platform equivalent.
• Functional shapes (Loading indicator, toggle states) MUST announce state changes via the host component, not the shape itself.

R5 — Per-preset variation

Per-preset shape disables MUST be declared explicitly in ui-style.kmd preset definition. Default fallback: missing preset config = all 35 enabled.

R6 — Forbidden patterns

• ❌ Inline polygon vertex math in component code (use the library binding)
• ❌ Shape morph without spring driver (per R2.2)
• ❌ Decorative shapes that animate continuously (battery drain, motion-sensitivity hazard) — only state-driven morphs allowed
• ❌ Shape morph between shapes whose semantic meaning differs (e.g., Heart → Triangle) — morphs MUST be within a semantic family (loading, like, button-state)

Cross-link

• shape.kmd — radius scale for rectangular surfaces
• motion.kmd R9 — spring tokens driving morphs
• themes/ui-style.kmd — per-preset shape config
• components/loading-indicator.kmd — primary morph consumer (#065)
• components/carousels.kmd — Hero variant morphs (#076)
• components/buttons.kmd — FAB morph, Split button trailing morph (#066)