Spec — Pickers (date + time)

Facet *isual*of Koder Design. Material parity: https://m3.material.io/components/date-pickers and https://m3.material.io/components/time-pickers.

Variant matrix

R1 — Date picker — modal (calendar)

Anatomy:

┌──────────────────────────────────────┐
│ Select date           ⌄  ⌃ Year      │
│ ────────────────────────────────────  │
│ ◂  May 2026                    ▸     │
│                                       │
│  S  M  T  W  T  F  S                 │
│                  1  2                 │
│  3  4  5  6  7  8  9                 │
│ 10 11 12 13 14 15 16                  │
│ 17 18 19 20 21 22 23                  │
│ 24 25 26 27 28 29 30                  │
│ 31                                    │
│                                       │
│                [Cancel]  [OK]         │
└──────────────────────────────────────┘

• *ontainer* dialog, 360 dp wide (mobile portrait) /

  328 dp (desktop)

• *eader* shows current selection in headline-small
• *onth navigation* arrows + month name; tap month opens year

  picker

• *ay grid* 7 columns, 6 rows max; current day with circle outline;

  selected day with filled circle (accent color)

• *ooter* Cancel + OK text buttons
• *oday indicator* 1 px circle outline on today's date
• *elected* filled circle, primary bg, on-primary text

R2 — Date picker — docked

Calendar floats below an anchor text field (no modal scrim). Used in forms with multiple date fields, where modal context-switch is heavy.

• Anchor: text field with calendar icon trailing
• On focus / icon tap: calendar appears below (above if no room)
• Closes when user picks a date OR clicks outside
• No scrim — page stays interactive

R3 — Date range picker

Twomonth sideby-side calendar:

┌──────────────────────────────────────────────────────┐
│  Start date  →  End date                              │
│  Mar 12      →  Mar 28                                │
│ ──────────────────────────────────────────────────── │
│ ◂  March 2026         April 2026                ▸    │
│                                                       │
│  S  M  T  W  T  F  S    S  M  T  W  T  F  S          │
│  ...                     ...                          │
│                                                       │
│                       [Cancel]  [Save]                │
└──────────────────────────────────────────────────────┘

• Two months visible; tapanddrag OR two-tap to define range
• Selected range: tonal bg (secondary-container) for days in range;

  filled circle on start + end

• Mobile (Compact): one month with scroll, range still applies

R4 — Time picker — dial

Anatomy:

┌───────────────────────────────┐
│        Select time             │
│ ─────────────────────────────  │
│         ┌─ 10 : 30 ─┐  AM  PM │
│         └───────────┘          │
│                                │
│            ╭─────╮             │
│         11 │  ● 12             │
│       10  ╱│       ╲ 1         │
│         9  │   ●   │ 2         │
│           ╲│       │            │
│         8  └─────┘  3          │
│           7  6  5  4            │
│                                │
│            [Cancel]  [OK]      │
└───────────────────────────────┘

• *isplay* HH : MM in large text; tap each segment to edit
• *ial* hour ring (12 positions) or minute ring (60 positions,

  shown as 12 multiples of 5)

• *M / PM*segmented button (12-hour locale only)
• *witch to keyboard* small icon toggles to Input variant

R5 — Time picker — input

Two text fields for HH and MM with : separator, plus AM/PM segmented button (12-hour locale only).

• Each field: numeric keyboard on mobile; typetoedit on desktop
• Auto-advance: typing 2 digits in HH jumps to MM field
• Validation: HH ∈ [0, 23] or [1, 12]; MM ∈ [0, 59]
• Smaller dialog than dial variant (no clock face)

Used as default on desktop AND as toggle from dial when user prefers keyboard.

R6 — Locale rules

Pickers ALWAYS respect locale (per i18n/contract.kmd):

Override via prop only if domain requires (e.g., 24-hour for medical schedules in en-US). Document why.

R7 — Constraints

Pickers support:

• min / max dates → outofrange days disabled (38% opacity, not

  selectable)

• disabledDates array → specific dates blocked (holidays, booked

  slots)

• disabledRanges for date range picker

Disabled dates are still navigable via keyboard but cannot be selected; screen reader announces "Disabled".

R8 — Keyboard

R9 — Accessibility

• Dialog wrapper: role="dialog" + aria-modal="true" +

  aria-labelledby (pointing to "Select date")

• Calendar grid: role="grid" + aria-label="Date picker"; each

  cell role="gridcell" with aria-selected on current

• Outofrange / disabled cells: aria-disabled="true"
• Today cell: aria-current="date"
• Time dial: role="slider" per ring (hour / minute) with

  aria-valuenow / valuemin / valuemax

• Time input fields: native <input type="number"> semantics; labels

  read "Hour" / "Minute"

• Screen reader announces selection: "Selected: Monday, May 11, 2026"

R10 — Animation

• *odal open* scalein 0.95 → 1 + fade (motionmedium)
• *onth change* slide horizontal (motion-medium)
• *ear picker* vertical scroll list (in-place, no slide)
• *ial click* hand rotates to target position

  (motionemphasizeddecelerate)

• *ange drag* tonal fill grows in real-time
• Reduced motion: instant transitions; no rotation animation

  (snap dial)

R11 — Per-preset variation

R12 — Density

R13 — Forbidden patterns

• ❌ Date picker without min / max for time-bounded contexts

  (birthdate, expiry, etc.)

• ❌ Time picker dial < 240 dp diameter (touch targets too small)
• ❌ Ignoring locale firstdayof-week
• ❌ Picker that requires server roundtrip per month change

  (latency)

• ❌ Picker without keyboard fallback (Input variant always available

  for accessibility)

• ❌ Calendar grid that scrolls vertically through years (use year

  picker overlay instead)

• ❌ Disabled dates without explanation (provide tooltip or

  description)

• ❌ Range picker that allows end < start without auto-swap

Cross-link

• i18n/contract.kmd — locale-aware formatting
• themes/color-roles.kmd — primary for selected, secondary-container for range
• themes/typography.kmd — headline-small for header, body-large for cells
• components/text-fields.kmd — anchor for docked variant
• components/dialogs.kmd — modal wrapper pattern
• interaction/states.kmd — disabled / selected layers
• foundations/elements.kmd — Control + Container families