# Scene density heatmap

> Who speaks in which scene: characters down the side, scenes across, four steps of one colour, the scene count at each row's end, and the scene open in the editor outlined.

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

## Usage

### What it is
A grid where each cell is one character in one scene, and its depth of colour is how much they speak there. Read across a row to see a character's path through the act; read down a column to see who shares a scene. Casting directors and 1st ADs use exactly this to group cast days: actors who share many scenes are scheduled together.

### When to use
- Characters by scene (lines spoken or simple presence), breakdown elements by scene, locations by act.
- When there are enough cells (about 20 or more) that a table alone is hard to scan.

### When not to
- To score scenes: no "tension", "energy" or "pace" heatmap. Kwark does not measure the quality of a story (Decisions 0002, 0004).
- For a person's activity by day. No heatmap of writing days, ever (Decision 0036).
- Fewer than about 20 cells. Use a table.

### Anatomy in use
- **Four steps of one hue**, not a continuous ramp: *No lines*, *1 or 2*, *3 to 6*, *7 or more*. Steps are easier to tell apart and say exactly what a colour means.
- **Scenes in script order** across the top; the scene open in the editor outlined and its number in coral.
- **Row totals** at the end: how many scenes the character speaks in.
- A legend under the grid in the same words as the table.

### Writing
The title says what depth means (*Who speaks in which scene*), and the range (*Act 2, Scenes 10–21*). The reading picks one fact a scheduler can use: *Arjun shares 5 of them.*

**Do:** Characters by scene in four coral steps with a labelled legend and row totals.

**Don't:** A red-to-green "tension" heatmap of the screenplay.

## Style

### Anatomy

1. **Frame**: `.kw-viz` card.
2. **Grid**: `112px repeat(n, 28px) 56px`, 3px gaps; scrolls sideways inside the card when n is large, names sticky.
3. **Cell**: 28 × 28px, 4px corners. Step 0 is `--k-raise`; steps 1–3 are `--k-chart-coral` at 28%, 60% and 100% on the surface.
4. **Current column**: 2px `--k-text` outline around each cell; header number in coral, 600.
5. **Names**: 12px 500 `--k-text`; scene numbers and totals 12px tabular `--k-text-2`.
6. **Legend**: 12px swatches with the step words.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-chart-coral` | #bf5d45 | var(--k-brand-coral) |
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-radius-card` | 10px |  |
| `--k-fs-meta` | 12px |  |

### States
| State | Look |
|---|---|
| Rest | Four steps |
| Current scene | Outlined column |
| Character never speaks in the range | Row of step 0, total *0* |
| Table | Every count, scenes as columns |

## 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
<figure class="kw-viz">
  <figcaption class="kw-viz__head"><div><p class="kw-viz__title">Who speaks in which scene · Act 2, Scenes 10–21</p><p class="kw-viz__reading">Mira speaks in 10 of these 12 scenes; Arjun shares 5 of them.</p></div><label class="kw-viz__switch"><input class="kw-visually-hidden" type="checkbox" role="switch" aria-label="Show lines by character and scene as a table"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="4" width="18" height="16" rx="2"/><path d="M3 10h18M3 15h18M9 10v10"/></svg><span>Table</span></label></figcaption>
  <div class="kw-viz__plot">
    <div class="kw-heat2" style="--kw-cols:12" aria-hidden="true">
      <span class="kw-heat2__corner">Scene</span><span class="kw-heat2__col">10</span><span class="kw-heat2__col">11</span><span class="kw-heat2__col is-here">12</span><span class="kw-heat2__col">13</span><span class="kw-heat2__col">14</span><span class="kw-heat2__col">15</span><span class="kw-heat2__col">16</span><span class="kw-heat2__col">17</span><span class="kw-heat2__col">18</span><span class="kw-heat2__col">19</span><span class="kw-heat2__col">20</span><span class="kw-heat2__col">21</span><span class="kw-heat2__total">Scenes</span>
      <span class="kw-heat2__name">Mira</span><i data-bin="3"></i><i data-bin="2"></i><i data-bin="3" class="is-here"></i><i data-bin="1"></i><i data-bin="0"></i><i data-bin="2"></i><i data-bin="3"></i><i data-bin="2"></i><i data-bin="0"></i><i data-bin="2"></i><i data-bin="3"></i><i data-bin="1"></i><span class="kw-heat2__total">10</span>
      <span class="kw-heat2__name">Arjun</span><i data-bin="0"></i><i data-bin="1"></i><i data-bin="2" class="is-here"></i><i data-bin="3"></i><i data-bin="2"></i><i data-bin="0"></i><i data-bin="0"></i><i data-bin="1"></i><i data-bin="2"></i><i data-bin="0"></i><i data-bin="2"></i><i data-bin="0"></i><span class="kw-heat2__total">7</span>
      <span class="kw-heat2__name">Meera</span><i data-bin="1"></i><i data-bin="0"></i><i data-bin="0" class="is-here"></i><i data-bin="0"></i><i data-bin="2"></i><i data-bin="2"></i><i data-bin="0"></i><i data-bin="0"></i><i data-bin="1"></i><i data-bin="2"></i><i data-bin="0"></i><i data-bin="0"></i><span class="kw-heat2__total">5</span>
      <span class="kw-heat2__name">The courier</span><i data-bin="0"></i><i data-bin="0"></i><i data-bin="0" class="is-here"></i><i data-bin="0"></i><i data-bin="0"></i><i data-bin="0"></i><i data-bin="1"></i><i data-bin="0"></i><i data-bin="0"></i><i data-bin="0"></i><i data-bin="0"></i><i data-bin="2"></i><span class="kw-heat2__total">2</span>
      <span class="kw-heat2__name">Lab tech</span><i data-bin="0"></i><i data-bin="2"></i><i data-bin="0" class="is-here"></i><i data-bin="0"></i><i data-bin="0"></i><i data-bin="0"></i><i data-bin="0"></i><i data-bin="0"></i><i data-bin="1"></i><i data-bin="0"></i><i data-bin="0"></i><i data-bin="0"></i><span class="kw-heat2__total">2</span>
    </div>
    <p class="kw-viz__foot kw-heat2__legend" aria-hidden="true"><span><i data-bin="0"></i>No lines</span><span><i data-bin="1"></i>1 or 2 lines</span><span><i data-bin="2"></i>3 to 6 lines</span><span><i data-bin="3"></i>7 lines or more</span><span class="kw-heat2__herekey">Scene 12, open in the editor</span></p>
  </div>
  <div class="kw-viz__table"><table><caption>Lines spoken by character, Scenes 10 to 21</caption><thead><tr><th scope="col">Character</th><th scope="col" class="num">Sc 10</th><th scope="col" class="num">Sc 11</th><th scope="col" class="num">Sc 12</th><th scope="col" class="num">Sc 13</th><th scope="col" class="num">Sc 14</th><th scope="col" class="num">Sc 15</th><th scope="col" class="num">Sc 16</th><th scope="col" class="num">Sc 17</th><th scope="col" class="num">Sc 18</th><th scope="col" class="num">Sc 19</th><th scope="col" class="num">Sc 20</th><th scope="col" class="num">Sc 21</th></tr></thead><tbody><tr><th scope="row">Mira</th><td class="num">9</td><td class="num">4</td><td class="num">12</td><td class="num">2</td><td class="num">0</td><td class="num">6</td><td class="num">8</td><td class="num">3</td><td class="num">0</td><td class="num">5</td><td class="num">7</td><td class="num">1</td></tr><tr><th scope="row">Arjun</th><td class="num">0</td><td class="num">2</td><td class="num">5</td><td class="num">9</td><td class="num">4</td><td class="num">0</td><td class="num">0</td><td class="num">2</td><td class="num">6</td><td class="num">0</td><td class="num">3</td><td class="num">0</td></tr><tr><th scope="row">Meera</th><td class="num">1</td><td class="num">0</td><td class="num">0</td><td class="num">0</td><td class="num">3</td><td class="num">5</td><td class="num">0</td><td class="num">0</td><td class="num">2</td><td class="num">4</td><td class="num">0</td><td class="num">0</td></tr><tr><th scope="row">The courier</th><td class="num">0</td><td class="num">0</td><td class="num">0</td><td class="num">0</td><td class="num">0</td><td class="num">0</td><td class="num">2</td><td class="num">0</td><td class="num">0</td><td class="num">0</td><td class="num">0</td><td class="num">3</td></tr><tr><th scope="row">Lab tech</th><td class="num">0</td><td class="num">3</td><td class="num">0</td><td class="num">0</td><td class="num">0</td><td class="num">0</td><td class="num">0</td><td class="num">0</td><td class="num">1</td><td class="num">0</td><td class="num">0</td><td class="num">0</td></tr></tbody></table></div>
</figure>
```

### Building it
Bin each count into a step (`data-bin="0…3"`) in the data layer, not in CSS, so the table and legend use the same thresholds. Generate the grid, the legend and the table from one array.

## Accessibility

### Screen readers
The grid is `aria-hidden`; the table lists every count with scenes as column headers and characters as row headers.

### Colour
Steps differ in lightness, so the grid reads in greyscale. The legend states each step in words, and the totals are text.

## For agents

### Rules

- **Never** score story quality with a heatmap.
- **Must** use one hue in labelled steps, with the thresholds written in the legend.
- **Never** draw a heatmap of a person's activity by day.
- **Must** keep scenes in script order.
- **Always** carry a table with every count.

### AI readiness test

**Task:** Show which characters share scenes so the 1st AD can group cast days.

**Give the agent:** Scene density heatmap, Stripboard strip, Cast board.

**Constraint:** Only speaking presence counts; Act 2 has 30 scenes.

**A reliable answer:**
- Rows are characters, columns scenes in order
- Four steps with the legend in words
- Row totals
- Grid scrolls with names sticky
- Table switch
