# Screenplay elements

> Scene heading, action, character, parenthetical, dialogue and transition, each with its printed indent and width.

Source: https://kwark.space/designSystem/components/screenplay-elements

## Usage

### When to use
Every screenplay surface uses these six elements and no others for the core page. Shots, music cues, on-screen text and lyrics are Kwark's additional writer elements and follow the same grid.

### The elements and their geometry
Measured from the left text margin (the action margin), in characters of 12pt Courier (10 per inch):

| Element | Indent | Width | Case | Space above |
|---|---|---|---|---|
| Scene heading | 0 | full | UPPERCASE, bold | 2 lines |
| Action | 0 | full | as written | 1 line |
| Character | 22ch (2.2in) | to the margin | UPPERCASE | 1 line |
| Parenthetical | 16ch (1.6in) | 28ch (2.8in), brackets included | lower case, italic on screen | none |
| Dialogue | 10ch (1.0in) | 33ch (3.3in) | as written | none |
| Transition | right-aligned | — | UPPERCASE, ends with a colon | 1 line |

### Conventions writers expect
- **Scene heading (slugline):** `INT.`, `EXT.` or `INT./EXT.`, the place, a dash, the time of day: *INT. EDIT SUITE – NIGHT*. Kwark reads I/E and D/N from it for the [Stripboard strip](https://kwark.space/designSystem/components/stripboard-strip.md), so keep that order.
- **Character extensions:** `(V.O.)`, `(O.S.)` or `(O.C.)`, and `(CONT’D)` when the same character speaks again after action. Extensions are part of the cue line.
- **Parenthetical:** a brief direction for the delivery. Brackets are drawn by the element, not typed.
- **Transitions:** `CUT TO:`, `DISSOLVE TO:`, `SMASH CUT TO:`, `MATCH CUT TO:`. `FADE IN:` sits at the left margin as the first line; `FADE OUT.` ends the script.

### When not to
- Never colour dialogue text by character. Kwark marks whose line it is with a 2px rule in the margin when character colours are on; the words stay ink.
- Never invent a seventh core element to solve a layout problem. Add a writer element only through a decision record.

### Writing
Placeholders in empty elements describe the element in plain words ("Where and when", "Who speaks"), never a sample line the writer might keep by accident.

**Do:** *MIRA (CONT’D)* at 22ch, then her line at 10ch wrapping at 33 characters.

**Don't:** A centred character name and dialogue that runs the full page width, as a word processor would draw it.

## Style

### Anatomy

Classes: `.kw-sp-scene`, `.kw-sp-action`, `.kw-sp-character`, `.kw-sp-paren`, `.kw-sp-dialogue`, `.kw-sp-transition`. Add `data-number` to a scene heading for margin numbers and `.kw-sp-revised` to a changed line for the revision star. `.kw-script-page--labelled` with `data-el` prints each element's name in the left margin, like the app's format ruler.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-font-screenplay` | 'Courier Prime', 'Courier New', monospace |  |
| `--k-fs-script` | 16px |  |
| `--k-accent` | #98633f | #98633f |
| `--k-text-2` | #5b6779 | #9ca3af |

## Code

### React

In the Kwark app: `import { Scene } from '@/pages/Understanding/EditorModule/nodes/Scene'`.

```tsx
// One TipTap node per element: nodes/Scene.ts, Action.ts, Character.ts,
// Parenthetical.ts, Transition.ts. Tab and Enter move between them (see Keyboard).
```

| Prop | Type | Notes |
|---|---|---|
| `type` | `'scene' \| 'action' \| 'character' \| 'parenthetical' \| 'dialogue' \| 'transition'` | the node name |

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<article class="kw-script-page kw-script-page--crop kw-script-page--labelled" aria-label="Screenplay elements, labelled">
<p class="kw-sp-scene" data-el="Scene heading">INT. EDIT SUITE – NIGHT</p>
<p class="kw-sp-action" data-el="Action">Mira scrubs back through Reel 3.</p>
<p class="kw-sp-character" data-el="Character">MIRA (CONT’D)</p>
<p class="kw-sp-paren" data-el="Parenthetical">not looking up</p>
<p class="kw-sp-dialogue" data-el="Dialogue">Run it from the top. Slowly this time.</p>
<p class="kw-sp-transition" data-el="Transition">CUT TO:</p>
</article>
```

## Accessibility

### Keyboard (as in the Kwark editor)
| Key | Does |
|---|---|
| Enter | Ends the element and starts the expected next one (character → dialogue → action) |
| Tab | Cycles the element type of the current line |
| Shift + Tab | Cycles backwards |
| ⌘ 1–6 | Sets scene heading, action, character, parenthetical, dialogue, transition |

- Announce the element type when it changes ("Dialogue"), in a polite live region.
- Uppercase is applied with CSS for cues and headings, so screen readers read words, not letters.

## For agents

### Rules

- **Must** use the six core elements with the indents in the table; never position them by eye.
- **Must** keep `INT./EXT. PLACE – TIME` order in scene headings, because the schedule reads tone from it.
- **Never** colour dialogue words by speaker; use the margin rule.
- **Always** draw parenthetical brackets with the element, never as typed characters.

### AI readiness test

**Task:** Add a "continued" cue when the same character speaks again after an action line.

**Give the agent:** Screenplay elements, Screenplay page.

**Constraint:** The writer can switch it off for the project.

**A reliable answer:**
- Appends (CONT’D) to the cue line at 22ch
- Only after an action interrupts the same speaker
- Switchable in settings, off means nothing is added
- Writer's text unchanged
