# File uploader

> Bring in a screenplay from wherever it was written: drop a Final Draft, Fountain, Celtx, Word or PDF file, watch it read, and see what it read before it lands.

Source: https://kwark.space/designSystem/components/file-upload

## Usage

### What it is
The file uploader is how a screenplay written somewhere else comes into Kwark. It is the system’s drawing of the editor’s Import step (`ImportModal.tsx`), and it carries what that code knows: the formats a writer is likely to arrive with (`importScreenplay.ts`: Final Draft, Fountain, Celtx, Fade In, Highland, Word, PDF, text), the 20 MB limit, and the rule that a file is **read and shown before it lands**. A page, not a cloud, is the mark: the thing being brought in is a script.

### The four moments
| Moment | What the person sees |
|---|---|
| Waiting | *Drop a screenplay*, the formats in words and as extensions, *Choose a file*. |
| Dragging over | A solid accent edge and *Release to read Blank Pages.fdx*. Nothing is added yet. |
| Reading | The file’s name, format and size; a thin bar counting pages; scenes found so far. *Stop* is always there. |
| Read | Pages, scenes and dialogue lines, and either *Every line read cleanly* or *3 lines want a look*. **Review and import** goes to the line-by-line review. |

### When to use
- Bringing in a screenplay, a schedule export, a cast list; any file that becomes structured Kwark data.

### When not to
- Replacing a project cover: the poster’s own *Replace cover* (Decision 0017).
- Attaching a reference image or a PDF to a research note: the note’s attachment control.

### Rules from the code
- Read what the format says. A Final Draft or Fountain file states each element; a PDF is guessed from layout. Say which it was (*Final Draft*), and prefer the source file when a person has both.
- Never add to the project until the person has seen the result. Importing into an existing script shows exactly what will change.
- Errors use Kwark’s sentence, not a library’s: *This file could not be read as a screenplay…* with what to try next.

**Do:** *Final Draft · 112 pages · 64 scenes · 412 dialogue lines* and **Review and import**.

**Don't:** A spinning loader and then a project silently full of mis-read scene headings.

## Style

### Anatomy

1. **Zone**: up to 520px, 24px 16px padding, a 1.5px dashed `--k-line-strong` edge, 10px corners, a step above the page. Hover: the edge darkens to `--k-text-2`.
2. **Page mark**: 42 × 54px sheet with a folded corner (3/10px corners) and five lines placed like a heading, action and a centred cue. It is the only picture, and it is the object being imported.
3. **Text**: *Drop a screenplay* in 600 16px; formats in 12px `--k-text-2` up to 40 characters a line; extensions as small 1px-line tags.
4. **Choose a file**: a secondary [Button](https://kwark.space/designSystem/components/button.md) wrapping a visually hidden `<input type="file">`, so keyboard, phone and screen reader all get the native picker.
5. **Over**: solid `--k-accent` edge, a 14% `--k-accent-soft` wash, the page lifts 3px.
6. **File row**: 30 × 38px page, name in 600 14px with format and figures under it in 12px tabular; actions on the right (below on a phone).
7. **Progress**: a 4px ink bar on `--k-raise`, with *Reading pages · 48 of 112* under it.
8. **Error**: the edge and page in `--k-danger`; the message with an alert glyph, and *Choose another* in the row.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-bg` | #f8fafc | #191919 |
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-line-strong` | var(--k-text-2) | var(--k-text-2) |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-accent` | #98633f | #98633f |
| `--k-accent-soft` | #e8b58b | #e8b58b |
| `--k-danger` | #b4382c | #e0685c |
| `--k-ok` | #2c6e49 | #6cc08a |
| `--k-radius-card` | 10px |  |
| `--k-fs-title` | 16px |  |

## 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-specimen-row">
<div class="kw-drop"><span class="kw-drop__page" aria-hidden="true"><i></i><i></i><i></i><i></i><i></i></span>
  <p class="kw-drop__title">Drop a screenplay</p>
  <p class="kw-drop__formats">Final Draft, Fountain, Celtx, Fade In, Highland, Word, PDF or plain text. Up to 20 MB.</p>
  <ul class="kw-drop__exts" aria-label="Formats"><li>.fdx</li><li>.fountain</li><li>.celtx</li><li>.docx</li><li>.pdf</li></ul>
  <label class="kw-button kw-drop__choose">Choose a file<input class="kw-visually-hidden" type="file" accept=".fountain,.fdx,.fdxt,.celtx,.fadein,.highland,.pdf,.txt,.md,.docx,.odt,.rtf"></label>
</div>
<div class="kw-drop kw-drop--over" aria-hidden="true"><span class="kw-drop__page" aria-hidden="true"><i></i><i></i><i></i><i></i><i></i></span>
  <p class="kw-drop__title">Release to read Blank Pages.fdx</p>
  <p class="kw-drop__formats">Nothing is added to the project until you have seen it.</p>
</div>
</div>
<div class="kw-specimen-row">
<div class="kw-drop kw-drop--file">
  <div class="kw-drop__row"><span class="kw-drop__page" aria-hidden="true"><i></i><i></i><i></i><i></i><i></i></span><p class="kw-drop__name">Blank Pages – draft 3.fdx<small>Final Draft · 412 KB</small></p><button class="kw-button kw-button--quiet kw-button--sm" type="button">Stop</button></div>
  <div class="kw-drop__bar" role="progressbar" aria-label="Reading Blank Pages – draft 3.fdx" aria-valuemin="0" aria-valuemax="112" aria-valuenow="48" aria-valuetext="48 of 112 pages"><span style="width:43%"></span></div>
  <p class="kw-drop__status"><span>Reading pages · 48 of 112</span><span>27 scenes so far</span></p>
</div>
<div class="kw-drop kw-drop--file">
  <div class="kw-drop__row kw-drop__row--two"><span class="kw-drop__page" aria-hidden="true"><i></i><i></i><i></i><i></i><i></i></span><p class="kw-drop__name">Blank Pages – draft 3.fdx<small>Final Draft · 112 pages · 64 scenes · 412 dialogue lines</small></p></div>
  <div class="kw-drop__status" role="status"><span class="kw-badge kw-badge--ok">Every line read cleanly</span><span class="kw-drop__actions"><button class="kw-button kw-button--quiet" type="button">Choose another</button><button class="kw-button kw-button--primary" type="button">Review and import</button></span></div>
</div>
</div>
<div class="kw-drop kw-drop--file kw-drop--error">
  <div class="kw-drop__row"><span class="kw-drop__page" aria-hidden="true"><i></i><i></i><i></i><i></i><i></i></span><p class="kw-drop__name">Scan_0041.pdf<small>PDF · 3.1 MB</small></p><label class="kw-button kw-button--sm kw-drop__choose">Choose another<input class="kw-visually-hidden" type="file" accept=".fountain,.fdx,.fdxt,.celtx,.fadein,.highland,.pdf,.txt,.md,.docx,.odt,.rtf"></label></div>
  <p class="kw-drop__err" role="alert"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10"/><path d="M12 8v4M12 16h.01"/></svg>This file could not be read as a screenplay. Check that it is a Final Draft, Fountain, Word, PDF or text file, or export it again from the app it came from.</p>
</div>
```

## Accessibility

### Keyboard
| Key | Does |
|---|---|
| Tab | Reaches *Choose a file* (the hidden input inside the label). |
| Enter / Space | Opens the system file picker. |
| Tab (reading) | Reaches *Stop*. |

### Roles and names
- Dropping is never the only way in: the native file input is always there, named by its visible label.
- The over state is visual only (`aria-hidden` in the specimen): dragging is a pointer gesture.
- Reading is a `role="progressbar"` named with the file, with `aria-valuetext` in pages (*48 of 112 pages*). Announce the start and the result once, not every page.
- The result and errors are announced (`role="status"` / `role="alert"`) and focus moves to **Review and import** or *Choose another*.
- `accept` lists the extensions, so the phone’s picker greys out files it cannot read.

## For agents

### Rules

- **Must** keep a real, labelled file input; never make drag and drop the only way to add a file.
- **Must** show what was read (pages, scenes, lines) before anything is added to the project.
- **Always** name the accepted formats in words and the size limit before a file is chosen.
- **Always** offer a way to stop a read in progress.
- **Never** use a cloud or upload-arrow illustration; the mark is the page being imported.

### AI readiness test

**Task:** Build the first step of importing a screenplay into an empty project.

**Give the agent:** File uploader, Button, the editor’s Import screenplay flow.

**Constraint:** Accept Final Draft, Fountain, Celtx, Fade In, Highland, Word, PDF and text up to 20 MB.

**A reliable answer:**
- Drop zone with Choose a file over a native input
- Formats in words
- Progress in pages with Stop
- Result counts before import
- Error uses Kwark’s sentence
