# Timecode display

> The clock of picture and sound: HH:MM:SS:FF in Poppins tabular figures, labelled with which clock it is and its frame rate, with a semicolon for drop-frame and typed relative entry.

Source: https://kwark.space/designSystem/components/timecode

## Usage

### What it is
Timecode is the address of a frame. Editors, assistants, colourists and mixers read it all day, call it out loud to each other and type it into every tool. Kwark writes it the way every post house does: `HH:MM:SS:FF`, hours to frames, with the frame rate and the clock named beside it.

Scene 12 of *Blank Pages* sits at **01:04:10:07** on the sequence clock, while the camera clock of the same frame (12B take 1) reads **14:22:30:19**. Both are right. A display that does not say which one it is showing is the start of a wrong conform.

### When to use
- Above or below every viewer, at the left of every timeline toolbar, in every list of clips, markers and cues.
- Wherever a person will read a time back to someone else: notes, ADR cues, VFX pulls, the EDL.

### When not to
- For script length or story time: say *page 14* or *2 min 10 s*.
- For playback in a review link on a phone where the viewer only needs to find their place: show the timecode, but never hide the frames.

### Clocks and how to label them
| Clock | Where it comes from | Label |
|---|---|---|
| Program (record) | The sequence. Many productions start at 01:00:00:00 | *Program* |
| Source | The clip's own clock, from camera or sound recorder | *Source · 12B-1* |
| Duration | In to out, or a clip's length | *In → out*, *Duration* |
| Remaining | Time left to the out mark | *Remaining* |

### Drop-frame
At 29.97 and 59.94 fps the clock drops frame **numbers** 00 and 01 at the start of every minute except every tenth, so it stays close to the wall clock. No frames are lost. It is written with a semicolon before the frames: `00:01:00;02`. Never show drop-frame at 23.976, 24, 25, 30 or 50 fps.

### Typed entry
Pro tools let you type a time without clicking first. Kwark's entry starts on any digit or on **+** / **−** while the viewer or timeline has focus: `+212` then Enter moves 2 seconds 12 frames later; `1041207` goes to 01:04:12:07 (missing leading pairs are filled from the current time). Esc cancels and puts the old time back.

**Do:** *Program 01:04:10:07 · 24 fps* beside *Source 14:22:30:19*, each labelled.

**Don't:** *0:10* with no frames, or two unlabelled timecodes side by side that disagree.

## Style

### Anatomy

1. **Label**: 12px Poppins 500 in `--k-text-2`, sentence case, names the clock: *Program*, *Source · 12B-1*.
2. **Value**: Poppins 500 with `font-variant-numeric: tabular-nums`, 20px in a display cell (`.kw-pro-tc--lg`), 14px in toolbars (`--md`), 12px in lists. Separators are the same size in `--k-text-2` so the digits group without changing width.
3. **Meta line**: 11px figures, 12px words: frame rate and drop or non-drop.
4. **Cell**: 10px 12px padding on `--k-pro-panel`, 1px `--k-pro-line` between cells. The active clock (where J/K/L go) has a 2px `--k-pro-playhead` rule on its left.
5. **Entry**: the cell becomes a field with a 1px `--k-text` outline; typed digits fill from the right, the pair being typed is underlined.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-pro-panel` | #f6f7f9 | #19191b |
| `--k-pro-head` | #eceff3 | #202023 |
| `--k-pro-line` | #d3d9e0 | rgba(255, 255, 255, .09) |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-pro-playhead` | #c4502f | #f28b71 |
| `--k-font-ui` | 'Poppins', system-ui, sans-serif |  |
| `--k-fs-head` | 20px |  |
| `--k-fs-dense` | 11px |  |
| `--k-fs-meta` | 12px |  |

### Numbers
| Part | Value |
|---|---|
| Display value | 20px / 1.1, weight 500, letter-spacing 0.01em |
| Toolbar value | 14px, weight 500 |
| List value | 12px, weight 400 |
| Cell padding | 10px 12px |
| Active rule | 2px, `--k-pro-playhead` |
| Minimum width | 11ch at the display size, so the cell never reflows as digits change |

Never use a monospace face for timecode in Kwark: Poppins' tabular figures already hold their width, and the UI keeps one family.

## 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-pro kw-pro-tcd">
  <div class="kw-pro-tcd__cell" data-active><span class="kw-pro-tcd__label">Program</span><output class="kw-pro-tc kw-pro-tc--lg" aria-label="Program timecode">01<i>:</i>04<i>:</i>10<i>:</i>07</output><span class="kw-pro-tcd__meta">24 fps · non-drop</span></div>
  <div class="kw-pro-tcd__cell"><span class="kw-pro-tcd__label">Source · 12B-1</span><output class="kw-pro-tc kw-pro-tc--lg" aria-label="Source timecode">14<i>:</i>22<i>:</i>30<i>:</i>19</output><span class="kw-pro-tcd__meta">Camera clock · A003C012</span></div>
  <div class="kw-pro-tcd__cell"><span class="kw-pro-tcd__label">In → out</span><output class="kw-pro-tc kw-pro-tc--lg" aria-label="Marked duration">00<i>:</i>00<i>:</i>06<i>:</i>06</output><span class="kw-pro-tcd__meta">150 frames</span></div>
  <div class="kw-pro-tcd__cell" data-df><span class="kw-pro-tcd__label">Trailer · 29.97 drop-frame</span><output class="kw-pro-tc kw-pro-tc--lg" aria-label="Drop-frame timecode 00 01 00 02">00<i>:</i>01<i>:</i>00<i>;</i>02</output><span class="kw-pro-tcd__meta">Semicolon: frame numbers 00 and 01 skipped</span></div>
  <div class="kw-pro-tcd__cell" data-editing><span class="kw-pro-tcd__label">Go to · typing</span><span class="kw-pro-tc kw-pro-tc--lg kw-pro-tcd__entry" role="textbox" aria-label="Go to timecode" tabindex="0"><i>+</i>00<i>:</i>00<i>:</i>02<i>:</i><u>12</u></span><span class="kw-pro-tcd__meta">Enter moves 2 s 12 f later · Esc cancels</span></div>
</div>
```

### State
```ts
type Timecode = { frames: number; rate: '23.976' | '24' | '25' | '29.97' | '30' | '50' | '59.94' | '60'; dropFrame: boolean };
// Store frames as an integer count from the clock's zero; format only for display.
```
Keep the exact rational rate (24000/1001 for 23.976) underneath; round only when you format.

## Accessibility

### Keyboard
| Key | Does |
|---|---|
| 0–9, + or − | Starts typed entry while the viewer or timeline has focus |
| Enter | Goes to the typed time |
| Esc | Cancels the entry, restores the time |
| Up / Down in entry | Steps the pair under the caret by one |

### ARIA
- The value is an `<output>` with `aria-label` naming the clock. It is not live during playback; announce the time on stop.
- Drop-frame cells carry an `aria-label` that reads the digits in pairs so a screen reader does not say "semicolon".
- The typed entry is `role="textbox"` with the current value as its accessible value.

## For agents

### Rules

- **Must** write timecode as `HH:MM:SS:FF` with tabular figures and name which clock it is.
- **Must** use a semicolon before the frames only for 29.97 and 59.94 drop-frame.
- **Always** show the frame rate within reach of the timecode (the cell meta line or the toolbar).
- **Never** convert source timecode to program timecode silently, or show them unlabelled side by side.
- **Never** drop the frames field to save space; shorten the label instead.

### AI readiness test

**Task:** Add the program and source time read-outs to a dailies viewer.

**Give the agent:** Timecode display, Video player, Editing kit.

**Constraint:** The camera ran at 23.976 fps; the dailies sequence starts at 01:00:00:00.

**A reliable answer:**
- Two labelled cells, Program and Source
- HH:MM:SS:FF with colons (no drop-frame at 23.976)
- Frame rate shown
- Typed entry with + for relative moves
- Output not live during playback
