Spec — Switch

Facet Visual do Koder Design. Material parity: https://m3.material.io/components/switch.

Anatomy

OFF:  ●────         (handle left, track muted)
ON:   ────●         (handle right, track accent)

• Track: 52×32 px (default), radius-full pill
• Handle (thumb): 24 px circle, shifts left↔right
• Hit zone: 48×48 px

R1 — Switch vs Checkbox

Critical distinction:

Rule of thumb: if user must click a "Save" button after, use checkbox. If the change persists the moment they toggle, use switch.

R2 — States

R3 — Optional icons

Switch can show icons inside handle/track:

Optional; doesn't change behavior. Material 3 default includes check/x in handle for accessibility (visual state cue beyond color).

R4 — Animation

• Handle slides smoothly left↔right on toggle (motion-fast, ~150ms)
• Track color animates simultaneously
• Reduced-motion: instant (no slide)
• Sound (optional, app-specific): subtle click on toggle

R5 — Optimistic state

When toggling has async effect (server save), follow optimistic pattern:

1. User toggles → switch UI immediately shifts to new state
2. Async call kicks off in background
3. If success: stay
4. If failure: snap back to previous state + show error snackbar ("Couldn't enable notifications. Try again.")

NEVER show a spinner WITHIN the switch on async — it freezes the visual feedback.

R6 — Settings convention

In Settings pages, switch rows have this canonical layout:

┌────────────────────────────────────────────────────┐
│ [icon?]  Title                              [●──]  │
│          Optional description text                 │
└────────────────────────────────────────────────────┘

• Icon (leading, optional)
• Title (title-medium)
• Description (body-small muted) below title
• Switch right-aligned (or left in RTL)
• Whole row clickable

KoderSettingsTile.toggle() widget (per future settings/patterns.kmd) — exposed by koder_kit.

R7 — Accessibility

• <input type="checkbox" role="switch"> (HTML standard, both attributes)
• OR native Flutter Switch widget
• aria-checked="true" / "false" (set automatically with role=switch)
• Visible focus ring
• Keyboard: Space toggles
• Screen reader announces: "Switch, Notifications, on" (or off)
• High-contrast: not just color — handle position is the primary cue

R8 — Forbidden patterns

• ❌ Switch for form submission semantics (use checkbox)
• ❌ Switch without label (always provide accessible name)
• ❌ Switch that requires confirm dialog after toggle (defeats the "immediate" semantic — use checkbox + button instead)
• ❌ More than ~10 switches in one page (becomes overwhelming; group into sub-sections)
• ❌ Tri-state switch (use radio group for >2 options)

R9 — Per-preset variation

Cross-link

• components/checkbox.kmd — vs switch decision
• interaction/states.kmd — state visuals
• themes/color-roles.kmd — accent track ON
• themes/motion.kmd — slide animation