# Colour wheels

> Primary correction: lift, gamma, gain and offset as four wheels with a hue ring, a puck, a master slider and Y R G B read-outs, under one row of contrast, pivot, saturation, temperature and tint.

Source: https://kwark.space/designSystem/components/colour-wheels

## Usage

### What it is
The colourist's main instrument. Each wheel moves the colour balance of one tonal range: **lift** the shadows, **gamma** the midtones, **gain** the highlights, **offset** everything. The puck is the direction and amount; the master slider under each wheel moves its brightness without changing colour. Numbers say exactly where each one is, so a grade can be matched, written down and repeated.

### When to use
- In a grading tool, on the selected node. With a control panel attached, the wheels mirror its trackballs.

### When not to
- For a simple exposure or white-balance fix in dailies: two sliders (Exposure, Temperature) are enough.
- For choosing a UI or project colour: that is the [Colour picker](https://kwark.space/designSystem/components/colour-picker.md).

### How the wheel maps
- The ring is the vectorscope's hue circle: red at about 11 o'clock, yellow at 9, green at 7, cyan at 5, blue at 3, magenta at 1. A puck pushed towards a hue on the wheel moves the trace the same way on the [Scopes](https://kwark.space/designSystem/components/video-scopes.md).
- Neutral is the centre. Lift, gamma and offset read 0.000 at neutral; gain reads 1.000.
- Double-click a wheel, or its Reset, to return it to neutral. ⌥ drag moves the master instead of the colour.

### The night look in the specimen
Lift pushed a little towards blue (cool shadows), gain towards warm (skin), gamma barely touched: the DP's note for Scene 12, *keep the monitor cool and Mira's skin warm*.

**Do:** Four wheels with numbers to three decimals and a master under each, contrast and pivot above.

**Don't:** A single rainbow disc with a glow, no numbers, and a puck that cannot be reset.

## Style

### Anatomy

1. **Parameter row** (32px): Contrast, Pivot, Saturation, Temperature (K), Tint, as scrubbable number fields.
2. **Wheel head**: name 12px 500, reset.
3. **Disc**: up to 132px; a 6px hue ring (conic, the vectorscope's angles), a neutral face in `--k-pro-control`, a centre cross at 1px.
4. **Puck**: 10px ring, 2px `--k-text`, positioned by its R G B offset.
5. **Master slider**: 4px track, 10px handle, a centre tick at neutral.
6. **Read-outs**: Y R G B in 11px tabular figures; R, G and B each with a 6px dot in their scope colour, never coloured text.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-pro-panel` | #f6f7f9 | #19191b |
| `--k-pro-control` | #ffffff | #2a2a2e |
| `--k-pro-line` | #d3d9e0 | rgba(255, 255, 255, .09) |
| `--k-hue-r` | #d4574b |  |
| `--k-hue-y` | #d9c050 |  |
| `--k-hue-g` | #5cb56f |  |
| `--k-hue-c` | #4fb8c4 |  |
| `--k-hue-b` | #4f73d6 |  |
| `--k-hue-m` | #bd5bb5 |  |
| `--k-scope-r` | #ff6a5c |  |
| `--k-scope-g` | #5fd889 |  |
| `--k-scope-b` | #5fa0ff |  |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |

### Numbers
| Part | Value |
|---|---|
| Disc | min(132px, the column), ring 6px |
| Face | `--k-pro-control`, cross 1px `--k-pro-line-strong` |
| Puck | 10px, 2px border; travel ±50% of the face radius |
| Read-outs | three decimals, true minus sign |
| Gap between wheels | 12px; four across from 560px, two across below |

## 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
<section class="kw-pro kw-pro-panel kw-pro-wheels" aria-label="Primaries, node 01 Balance">
  <div class="kw-pro-bar"><strong>Primaries</strong><span class="kw-pro-dim kw-pro-ellip">Clip 04 · node 01 Balance</span><span class="kw-pro-sp"></span><div class="kw-pro-seg kw-pro-seg--text" role="group" aria-label="Controls"><button type="button" aria-pressed="true">Wheels</button><button type="button" aria-pressed="false">Bars</button><button type="button" aria-pressed="false">Log</button></div></div>
  <div class="kw-pro-wheels__params"><label class="kw-pro-num"><span>Contrast</span><input type="text" inputmode="decimal" value="1.080" aria-label="Contrast"></label><label class="kw-pro-num"><span>Pivot</span><input type="text" inputmode="decimal" value="0.435" aria-label="Pivot"></label><label class="kw-pro-num"><span>Sat</span><input type="text" inputmode="decimal" value="52.0" aria-label="Saturation"></label><label class="kw-pro-num"><span>Temp</span><input type="text" inputmode="decimal" value="−120" aria-label="Temperature"><em>K</em></label><label class="kw-pro-num"><span>Tint</span><input type="text" inputmode="decimal" value="+4.0" aria-label="Tint"></label></div>
  <div class="kw-pro-wheels__row">
    <div class="kw-pro-wheel" style="--x:15%;--y:4%">
    <div class="kw-pro-wheel__head"><strong>Lift</strong><button class="kw-pro-btn" type="button" aria-label="Reset lift" title="Reset lift"><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="M3 12a9 9 0 1 0 2.7-6.4L3 8M3 3v5h5"/></svg></button></div>
    <div class="kw-pro-wheel__disc" role="slider" tabindex="0" aria-label="Lift colour balance" aria-valuetext="Red −0.020, green +0.004, blue +0.031"><span class="kw-pro-wheel__ring"></span><span class="kw-pro-wheel__face"></span><i class="kw-pro-wheel__puck"></i></div>
    <div class="kw-pro-wheel__master" role="slider" tabindex="0" aria-label="Lift master" aria-valuetext="−0.012"><i style="left:44%"></i></div>
    <div class="kw-pro-wheel__vals"><span><b>Y</b> −0.012</span><span data-c="r"><b>R</b> −0.020</span><span data-c="g"><b>G</b> +0.004</span><span data-c="b"><b>B</b> +0.031</span></div>
  </div>
    <div class="kw-pro-wheel" style="--x:3%;--y:8%">
    <div class="kw-pro-wheel__head"><strong>Gamma</strong><button class="kw-pro-btn" type="button" aria-label="Reset gamma" title="Reset gamma"><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="M3 12a9 9 0 1 0 2.7-6.4L3 8M3 3v5h5"/></svg></button></div>
    <div class="kw-pro-wheel__disc" role="slider" tabindex="0" aria-label="Gamma colour balance" aria-valuetext="Red −0.006, green +0.004, blue +0.012"><span class="kw-pro-wheel__ring"></span><span class="kw-pro-wheel__face"></span><i class="kw-pro-wheel__puck"></i></div>
    <div class="kw-pro-wheel__master" role="slider" tabindex="0" aria-label="Gamma master" aria-valuetext="+0.006"><i style="left:53%"></i></div>
    <div class="kw-pro-wheel__vals"><span><b>Y</b> +0.006</span><span data-c="r"><b>R</b> −0.006</span><span data-c="g"><b>G</b> +0.004</span><span data-c="b"><b>B</b> +0.012</span></div>
  </div>
    <div class="kw-pro-wheel" style="--x:-9%;--y:-8%">
    <div class="kw-pro-wheel__head"><strong>Gain</strong><button class="kw-pro-btn" type="button" aria-label="Reset gain" title="Reset gain"><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="M3 12a9 9 0 1 0 2.7-6.4L3 8M3 3v5h5"/></svg></button></div>
    <div class="kw-pro-wheel__disc" role="slider" tabindex="0" aria-label="Gain colour balance" aria-valuetext="Red 1.040, green 1.012, blue 0.962"><span class="kw-pro-wheel__ring"></span><span class="kw-pro-wheel__face"></span><i class="kw-pro-wheel__puck"></i></div>
    <div class="kw-pro-wheel__master" role="slider" tabindex="0" aria-label="Gain master" aria-valuetext="1.020"><i style="left:56%"></i></div>
    <div class="kw-pro-wheel__vals"><span><b>Y</b> 1.020</span><span data-c="r"><b>R</b> 1.040</span><span data-c="g"><b>G</b> 1.012</span><span data-c="b"><b>B</b> 0.962</span></div>
  </div>
    <div class="kw-pro-wheel" style="--x:-2%;--y:1%">
    <div class="kw-pro-wheel__head"><strong>Offset</strong><button class="kw-pro-btn" type="button" aria-label="Reset offset" title="Reset offset"><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="M3 12a9 9 0 1 0 2.7-6.4L3 8M3 3v5h5"/></svg></button></div>
    <div class="kw-pro-wheel__disc" role="slider" tabindex="0" aria-label="Offset colour balance" aria-valuetext="Red +0.003, green 0.000, blue −0.002"><span class="kw-pro-wheel__ring"></span><span class="kw-pro-wheel__face"></span><i class="kw-pro-wheel__puck"></i></div>
    <div class="kw-pro-wheel__master" role="slider" tabindex="0" aria-label="Offset master" aria-valuetext="0.000"><i style="left:50%"></i></div>
    <div class="kw-pro-wheel__vals"><span><b>Y</b> 0.000</span><span data-c="r"><b>R</b> +0.003</span><span data-c="g"><b>G</b> 0.000</span><span data-c="b"><b>B</b> −0.002</span></div>
  </div>
  </div>
</section>
```

### Model
```ts
type Primaries = { lift: RGBY; gamma: RGBY; gain: RGBY; offset: RGBY; contrast: number; pivot: number; saturation: number; temperature: number; tint: number };
type RGBY = { r: number; g: number; b: number; y: number }; // lift/gamma/offset neutral 0, gain neutral 1
```
Exchange a primary grade as ASC CDL (slope, offset, power per channel plus saturation) when it has to reach another app.

## Accessibility

### Keyboard
| Key | Does |
|---|---|
| Arrows on a disc | Move the puck by 0.001 (⇧ ×10) |
| ⌥ ← / → | Master down / up |
| Delete or double-click | Reset the wheel |
| Tab | Next wheel or field |

### ARIA
- Each disc is `role="slider"` with `aria-valuetext` in channel words: *Red −0.020, green +0.004, blue +0.031*.
- The master is its own slider.
- Read-outs repeat the values as text, so nothing depends on seeing the puck or the ring.

## For agents

### Rules

- **Must** show numeric read-outs for every wheel and let people type them.
- **Must** place hues on the ring at the vectorscope's angles so the wheel and the scope agree.
- **Always** give each wheel a reset and a master separate from its colour.
- **Never** colour the read-out text by channel; mark the channel with a dot and a letter.
- **Never** apply a wheel move to more than the selected node without saying so.

### AI readiness test

**Task:** Build the primaries panel of a dailies grading tool.

**Give the agent:** Colour wheels, Video scopes, Colour grading kit.

**Constraint:** Values must round-trip to ASC CDL for the colourist.

**A reliable answer:**
- Lift, gamma, gain, offset with numeric read-outs
- Master sliders
- Contrast, pivot, saturation, temperature, tint row
- Ring at vectorscope angles
- Reset per wheel
- CDL export named
