# Revision mark

> How Kwark marks what a machine proposed from the writer’s own material: a margin star and a dotted rule, until a person makes it their own.

Source: https://kwark.space/designSystem/components/revision-mark

## Usage

### What it marks
Only what a machine may do in Kwark ([AI and authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md)): **find**, **move**, **carry** or **convert** the writer’s own material. Never new story words, never a better version of a line, never a verdict (Decision 0002).

| Allowed proposal | Example | Source label |
|---|---|---|
| Move the writer’s words to a new place | The beat *Mira finds the splice in the edit suite, night* proposed as the heading INT. EDIT SUITE – NIGHT | *Suggested · from your outline, Act 2* |
| Find something on the page | ZIPPO offered to the breakdown as a prop | *The script mentions · Scene 12* |
| Convert how words are typed | *naan ingey irukken* shown as நான் இங்கே இருக்கேன் | *Converted · Tamil* |
| Carry into production | Scene 12’s cast proposed for the Day 3 call sheet | *From the schedule, Day 3* |

### Why a revision mark, not a glow
In a revised shooting script a changed line gets an asterisk in the right margin, and writers, directors and script supervisors already read it as *this is new, look at it*. Kwark uses the same sign. It is quiet, it prints (Decision 0005), and it makes no claim about quality: it says only *this came from somewhere else*.

### The life of a mark
1. **Suggested.** Tint, dotted rule, margin star, and a label naming the source. Nothing is saved into the work.
2. **Accepted.** Tint and star go. History keeps where it came from.
3. **Edited.** The moment a person changes it, it is theirs. No mark.
4. **Not needed.** It goes, and the same proposal is not offered again.
5. **Undone.** Accepting was one step; Undo takes it back.

**Do:** INT. EDIT SUITE – NIGHT marked with the margin star and *Suggested · from your outline, Act 2*, with Use heading, Edit and Not needed.

**Don't:** Three “stronger” versions of Mira’s dialogue, a sparkle, or a glow that makes machine text the brightest thing on the page.

## Style

### Anatomy

1. **Tint**: `--k-rev-bg` behind the proposed words.
2. **Rule**: 1.5px dotted `--k-rev-line` under them.
3. **Margin star**: Courier Prime 700 in `--k-rev`, in the right margin, as on a revised page.
4. **Label**: dashed pill naming the source (*from your outline, Act 2*).
5. **Reason**: one plain sentence, e.g. the beat it came from.
6. **Answers**: Use, Edit, Not needed, per item.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-rev` | #346a58 | #9fd4bf |
| `--k-rev-bg` | #e4f1eb | #1b2b25 |
| `--k-rev-line` | #8cc3ae | #4f8a74 |

## 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 style="display:grid;gap:10px;max-width:460px">
<p class="kw-rev-line" style="font:400 var(--k-fs-subtitle)/1.7 var(--k-font-screenplay);margin:0">INT. <span class="kw-rev">EDIT SUITE – NIGHT</span></p>
<span class="kw-rev-label">* Suggested · from your outline, Act 2</span>
<p class="kw-hint" style="margin:0">From the beat “Mira finds the splice in the edit suite, night.”</p>
<div style="display:flex;gap:8px;flex-wrap:wrap"><button class="kw-button kw-button--sm kw-button--primary" type="button">Use heading</button><button class="kw-button kw-button--sm" type="button">Edit</button><button class="kw-button kw-button--sm kw-button--quiet" type="button">Not needed</button></div>
</div>
```

## Accessibility

- Never rely on the tint: the label says *Suggested* in words, linked to the proposed text with `aria-describedby`.
- Use, Edit and Not needed are buttons named with their object: *Use heading INT. EDIT SUITE – NIGHT*.
- On acceptance announce *Heading added* politely; Undo is one keystroke away (Cmd+Z).

## For agents

### Rules

- **Must** mark every machine proposal with a revision mark and a source label until a person accepts or edits it.
- **Never** use the mark for new story words, rewritten dialogue or any judgement of the work; a machine may only find, move, carry or convert the writer’s own material (Decision 0002).
- **Never** use glows, gradients or sparkles to signal machine help.
- **Must** give each proposal its own Use and Not needed; never Accept all into the script.
- **Always** drop the mark the moment a person edits the words.

### AI readiness test

**Task:** Propose scene headings for Act 2 from the writer's outline beats.

**Give the agent:** Revision mark, AI and authorship, Decision 0002.

**Constraint:** Some beats have no place or time of day.

**A reliable answer:**
- Proposes only headings built from the beat's own words, each marked Suggested · from your outline with the beat as the reason
- Leaves beats without a place unproposed or asks
- Offers Use, Edit and Not needed per heading with no Accept all
- Writes no dialogue or action and judges nothing
