# Time picker

> A call time, the way the call sheet prints it: large 24-hour figures, the shoot’s time zone, quick picks for unit call and sunrise, and +1 when the day runs past midnight.

Source: https://kwark.space/designSystem/components/time-picker

## Usage

### What it is
A time picker sets one time of day on a production document: crew call, shooting call, breakfast, lunch, wrap, a pickup. It is drawn like the box in the top corner of the call sheet: the figures are the largest thing in it, in Poppins with tabular numerals, so 06:00 and 11:11 take the same width and a column of times lines up.

Three things make it Kwark’s and not a clock widget:
- **The zone is always on the card.** A call time belongs to the place the unit is standing in, not to the device that typed it. *IST* sits beside the date, with *India Standard Time (Asia/Kolkata)* on hover and to screen readers.
- **Quick picks come from the day.** *Unit call* repeats the time already set for the unit; *Sunrise* comes from the location’s sun times (the same figure the call sheet prints). Beside the figures, *+15* and *−15* nudge without retyping, and are the thumb’s way to step on a phone.
- **Overnight is said, not guessed.** A wrap of 01:30 after a 06:00 call is the next morning. The card shows **+1** and the real date, *Tue 24 Nov*, so nobody reads it as half past one that afternoon.

### When to use
- Any time on the call sheet, the schedule, a calendar event or a pickup list.
- Times relative to the day (*31 min before sunrise*) are shown as a line under the figures, never as a replacement for them.

### When not to
- **A duration** (*45 min of setup*): use a [Number stepper](https://kwark.space/designSystem/components/number-stepper.md) with a unit.
- **A position in footage** (*00:14:03:12*): that is timecode; use the [Slider](https://kwark.space/designSystem/components/slider.md) scrub or a timecode field.
- **A date and time together on a phone**: two fields, the [Date picker](https://kwark.space/designSystem/components/date-picker.md) first, then this.

### The 24-hour clock
Call sheets print 24-hour times, so the picker does too: 06:00, 13:00, 17:44. A person can choose a 12-hour display in their settings; the stored value is still *HH:MM* plus the date and zone. Never show *AM/PM* on an issued call sheet.

### Overnight and +1
- When a time is earlier than the time it follows on the same day (wrap after call), set it on the next date and show **+1** with that date.
- Never silently roll a time over. If the person types 05:30 for a shooting call after a 06:00 crew call, that is an error with a way out, not a next-day time.
- Night shoots that *start* after midnight keep their own date: Day 8’s 00:30 call is on Day 8’s date, not *+1* of Day 7.

### Issued times (Decision 0020)
Once a call sheet is issued, its times are frozen. The card turns dashed and read-only, says *Issued in Rev 3*, and offers **Change in Rev 4**, which opens the next revision. Never edit an issued time in place.

**Do:** 06:00 in large tabular figures, *IST* beside *Mon 23 Nov · Day 7*, and a wrap of 01:30 marked **+1 · Tue 24 Nov**.

**Don't:** A native `<input type="time">` showing *1:30 AM* with no date, no zone and a spinner that differs on every browser.

### Writing
- The label is the call it sets: *Crew call*, *Shooting call*, *Wrap*. Never *Time*.
- Relations are facts, in words and figures: *31 min before sunrise at 06:31*, *19 h 30 min after crew call*. No advice about turnaround: Kwark records the day, it does not judge it.
- Errors name both times and the fix: *Shooting call is before crew call (06:00). Change one of them.*

## Style

### Anatomy

1. **Card**: `--k-surface`, 1px `--k-line`, 10px corners, 16px padding, up to 340px wide. Compact (12px padding) for secondary times.
2. **Top line**: the label (`.kw-label`, Poppins 500 12px) on the left; date, shoot day and the zone tag on the right, 12px `--k-text-2`. Zone tag: 600 12px, 1px line, 6px corners.
3. **Figures**: two segments, hour and minutes, each a text input with `inputmode="numeric"`. Poppins 600 at `--k-fs-paper-call` (44px) on the main card and `--k-fs-display` (28px) when compact; tabular, lining, −0.02em tracking. Segment box 52px tall (56 on a phone), 6px corners. The colon is 500 weight in `--k-text-2`, lifted 3px to sit at the figures’ middle.
4. **Next-day mark**: *+1* as a pill in `--k-cal-shoot-bg` / `--k-cal-shoot-ink` with the date below, after a 1px divider.
5. **Relation line**: 12px `--k-text-2`, with a 14px sun or moon glyph in `--k-cal-reading`.
6. **Nudges**: *+15* over *−15*, 30px pills (44 on touch) at the right of the figures.
7. **Quick picks**: 30px pills (44px on touch), 1px line, label in `--k-text-2` and the figure in 600 `--k-text`. Pressed: `--k-accent-soft` line on an 18% tint.

### States
| State | Look |
|---|---|
| Rest | Segments transparent; the figures alone. |
| Hover | Segment takes `--k-raise`. |
| Focus | Segment takes a 22% `--k-accent-soft` tint and a `--k-line-strong` edge; keyboard focus adds the 2px `--k-focus` ring. |
| Error | Card edge and figures in `--k-danger`; the message under them with an alert glyph. |
| Issued | Dashed edge, a step darker ground, read-only segments, *Issued in Rev 3* and *Change in Rev 4*. |
| Disabled | Not used. A time someone cannot change is shown issued or as text, with the reason. |

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-fs-paper-call` | 44px |  |
| `--k-fs-display` | 28px |  |
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-line-strong` | var(--k-text-2) | var(--k-text-2) |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-accent-soft` | #e8b58b | #e8b58b |
| `--k-cal-shoot-bg` | #f0ebd6 | #2d2919 |
| `--k-cal-shoot-ink` | #4d4019 | #e5d89e |
| `--k-cal-reading` | #a87b32 | #dcb36a |
| `--k-danger` | #b4382c | #e0685c |
| `--k-ok` | #2c6e49 | #6cc08a |
| `--k-radius-card` | 10px |  |
| `--k-radius-control` | 6px |  |
| `--k-radius-pill` | 999px |  |

## Code

### React

Use the HTML below with `kwark.css`. The example shows the markup and styling. Supply any application behavior described on this page.

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div class="kw-specimen-row">
<div class="kw-time" role="group" aria-label="Crew call, Day 7, Monday 23 November, India Standard Time">
  <div class="kw-time__top"><span class="kw-label">Crew call</span><span class="kw-time__when">Mon 23 Nov · Day 7 <abbr class="kw-time__zone" title="India Standard Time (Asia/Kolkata)">IST</abbr></span></div>
  <div class="kw-time__face"><input class="kw-time__seg" type="text" inputmode="numeric" maxlength="2" value="06" role="spinbutton" aria-valuemin="0" aria-valuemax="23" aria-valuenow="6" aria-label="Crew call hour, 24-hour clock"><span class="kw-time__colon" aria-hidden="true">:</span><input class="kw-time__seg is-focus" type="text" inputmode="numeric" maxlength="2" value="00" role="spinbutton" aria-valuemin="0" aria-valuemax="59" aria-valuenow="0" aria-label="Crew call minutes"><span class="kw-time__nudge" role="group" aria-label="Nudge crew call"><button class="kw-time__pick kw-time__pick--nudge" type="button" aria-label="15 minutes later"><b>+15</b></button><button class="kw-time__pick kw-time__pick--nudge" type="button" aria-label="15 minutes earlier"><b>−15</b></button></span></div>
  <p class="kw-time__rel"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="4"/><path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4"/></svg>31 min before sunrise at 06:31</p>
  <div class="kw-time__picks" role="group" aria-label="Quick times for crew call">
    <button class="kw-time__pick" type="button" aria-pressed="true">Unit call <b>06:00</b></button>
    <button class="kw-time__pick" type="button" aria-pressed="false">Sunrise <b>06:31</b></button>
  </div>
</div>
<div style="display:grid;gap:16px">
<div class="kw-time kw-time--compact" role="group" aria-label="Wrap, after midnight, Tuesday 24 November">
  <div class="kw-time__top"><span class="kw-label">Wrap</span><span class="kw-time__when"><abbr class="kw-time__zone" title="India Standard Time (Asia/Kolkata)">IST</abbr></span></div>
  <div class="kw-time__face"><input class="kw-time__seg" type="text" inputmode="numeric" maxlength="2" value="01" role="spinbutton" aria-valuemin="0" aria-valuemax="23" aria-valuenow="1" aria-label="Wrap hour, 24-hour clock"><span class="kw-time__colon" aria-hidden="true">:</span><input class="kw-time__seg" type="text" inputmode="numeric" maxlength="2" value="30" role="spinbutton" aria-valuemin="0" aria-valuemax="59" aria-valuenow="30" aria-label="Wrap minutes"><span class="kw-time__next"><span class="kw-time__plus" title="The next day">+1</span><small>Tue 24 Nov</small></span></div>
  <p class="kw-time__rel"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M20 14.5A8 8 0 1 1 9.5 4a6.5 6.5 0 0 0 10.5 10.5z"/></svg>19 h 30 min after crew call</p>
</div>
<div class="kw-time kw-time--compact kw-time--error" role="group" aria-label="Shooting call">
  <div class="kw-time__top"><span class="kw-label">Shooting call</span><span class="kw-time__when"><abbr class="kw-time__zone" title="India Standard Time (Asia/Kolkata)">IST</abbr></span></div>
  <div class="kw-time__face"><input aria-invalid="true" class="kw-time__seg" type="text" inputmode="numeric" maxlength="2" value="05" role="spinbutton" aria-valuemin="0" aria-valuemax="23" aria-valuenow="5" aria-label="Shooting call hour, 24-hour clock"><span class="kw-time__colon" aria-hidden="true">:</span><input aria-invalid="true" class="kw-time__seg" type="text" inputmode="numeric" maxlength="2" value="30" role="spinbutton" aria-valuemin="0" aria-valuemax="59" aria-valuenow="30" aria-label="Shooting call minutes"></div>
  <p class="kw-time__msg" role="alert"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10"/><path d="M12 8v4M12 16h.01"/></svg>Shooting call is before crew call (06:00). Change one of them.</p>
</div>
<div class="kw-time kw-time--compact kw-time--issued" role="group" aria-label="Crew call, issued">
  <div class="kw-time__top"><span class="kw-label">Crew call</span><span class="kw-time__when">Day 4 <abbr class="kw-time__zone" title="India Standard Time (Asia/Kolkata)">IST</abbr></span></div>
  <div class="kw-time__face"><input readonly class="kw-time__seg" type="text" inputmode="numeric" maxlength="2" value="07" role="spinbutton" aria-valuemin="0" aria-valuemax="23" aria-valuenow="7" aria-label="Crew call hour"><span class="kw-time__colon" aria-hidden="true">:</span><input readonly class="kw-time__seg" type="text" inputmode="numeric" maxlength="2" value="30" role="spinbutton" aria-valuemin="0" aria-valuemax="59" aria-valuenow="30" aria-label="Crew call minutes"></div>
  <p class="kw-time__msg"><span>Issued in <span class="kw-time__rev">Rev 3</span></span><button class="kw-linkbtn" type="button">Change in Rev 4</button></p>
</div>
</div>
</div>
```

### Behaviour to supply
- Each segment accepts digits only. Two digits in the hour move focus to the minutes. Backspace in an empty minutes segment returns to the hour.
- Up and Down step the focused segment (hours by 1, minutes by 5; Shift steps minutes by 1). Page Up and Page Down step by 15 minutes.
- Store `{ date: '2026-11-23', time: '06:00', zone: 'Asia/Kolkata', nextDay: false }`. Never store a UTC instant for a call time: it moves when someone travels.
- *Sunrise* is offered only when the location has sun times; otherwise the pick is absent, not disabled.

## Accessibility

### Keyboard
| Key | Does |
|---|---|
| Tab | Hour, then minutes, then each quick pick. |
| 0–9 | Types into the segment; the second hour digit moves to minutes. |
| Up / Down | Steps the segment (minutes by 5). |
| Shift + Up / Down | Steps minutes by 1. |
| Page Up / Page Down | ±15 minutes. |
| Home / End | 00 and 23 (or 55) in the segment. |

### Roles and names
- The card is `role="group"` named with the call, the date and the zone: *Crew call, Day 7, Monday 23 November, India Standard Time*.
- Each segment is an `<input>` with `role="spinbutton"`, `aria-valuemin`, `aria-valuemax`, `aria-valuenow` and a name that includes *24-hour clock* on the hour.
- The zone is an `<abbr>` with its full name in `title`.
- *+1* is also in words for screen readers: the group name says *after midnight, Tuesday 24 November*.
- Unit call and Sunrise are toggle buttons with `aria-pressed`; −15 and +15 are plain buttons with full names (*15 minutes earlier*).
- The error is `role="alert"` and both segments get `aria-invalid="true"`.
- Colour never carries the state alone: the error has words, *+1* has the date, issued has *Issued in Rev 3*.

## For agents

### Rules

- **Must** show the shoot’s time zone on every time picker, with the full zone name available to hover and screen readers.
- **Must** store a call time as a local date, time and IANA zone; never as a UTC instant.
- **Always** mark a time that falls on the next date with +1 and that date; never roll a time past midnight silently.
- **Never** use a native `<input type="time">` or AM/PM on a call sheet; use 24-hour tabular figures.
- **Never** edit an issued time in place; offer the next revision (Decision 0020).
- **Always** draw the figures in Poppins with tabular numerals, never Courier and never the monospace font.

### AI readiness test

**Task:** Add crew call and wrap to the Day 7 call sheet editor.

**Give the agent:** Time picker, Call sheet, Decision 0020.

**Constraint:** The unit shoots in Mumbai; the wrap is after midnight; Rev 3 is already issued.

**A reliable answer:**
- Two time cards labelled Crew call and Wrap
- IST shown with Asia/Kolkata as its full name
- Wrap shows +1 and Tue 24 Nov
- Issued times are read-only with Change in Rev 4
- Stored as date, time and zone
