# Textarea

> Several lines of plain text, such as a logline, notes or a description, that grow with what is written and keep the height a person sets.

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

## Usage

### What it is
The app’s `Textarea` (`components/ui/Textarea.tsx`) is a plain, unformatted multi-line field: loglines, notes for a department, a location’s description, a director’s note. It resizes vertically only, starts at three rows and keeps any height the person drags it to.

### When to use
- Plain text longer than one line, with no formatting.

### When not to
- **The screenplay.** Never. The script has its own editor with elements, pages and revision marks.
- One line (a title, a name): [Text input](https://kwark.space/designSystem/components/text-input.md).
- Text with structure (lists, headings): the notes editor.

### Counting, not judging
- A logline shows its length in words (*27 words*), because that is how loglines are talked about. It is a count, never a score, a grade or a suggestion (Decision 0002; Kwark never judges the script).
- A hard limit belongs to somewhere else (a festival form’s 300 characters). Show *312 of 300 characters*, keep every character, and say what the limit is for. Never cut the person’s text.

### Behaviour
- Grows with its content up to about ten lines, then scrolls. A height the person sets wins.
- Saves like every Kwark field: quietly, with the save status in the header. Never a Save button beside a single note.
- Read only: dashed edge, no fill, who wrote it under it.

**Do:** *27 words* above a logline, and *312 of 300 characters* that keeps all 312.

**Don't:** A counter that turns red at 40 words and a field that silently stops accepting text.

## Style

### Anatomy

1. **Box**: the text input box, at least 88px (three rows), 7px 10px padding, line height 1.55. Resize: vertical only.
2. **Logline**: 16px text (`--k-fs-title`) at 1.5, because it is read aloud and pitched.
3. **Label row**: the label on the left, the count on the right in 12px tabular `--k-text-2`; past a limit the count turns `--k-warn` and 500.
4. **Hint or error**: 12px under the box; the error with an alert glyph.

### States
| State | Look |
|---|---|
| Hover | `--k-line-strong` edge. |
| Focus | `--k-accent-soft` edge and the 2px ring. |
| Error | `aria-invalid="true"`, `--k-danger` edge (also while focused). |
| Read only | No fill, dashed edge. |
| Disabled | 50%; prefer read only with a reason. |

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-bg` | #f8fafc | #191919 |
| `--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-soft` | #e8b58b | #e8b58b |
| `--k-danger` | #b4382c | #e0685c |
| `--k-warn` | #8a5a00 | #d8a44a |
| `--k-radius-control` | 6px |  |
| `--k-fs-title` | 16px |  |

## Code

### React

In the Kwark app: `import Textarea from '@/components/ui/Textarea'`.

```tsx
<Textarea label="Logline" rows={2} value={logline}
  onChange={e => setLogline(e.target.value)} aria-describedby="logline-count" />
```

| Prop | Type | Notes |
|---|---|---|
| `label` | `string` | Visible label, tied by id. |
| `resizable` | `boolean` | Default true: vertical resize only. |
| `rows` | `number` | Default 3. |
| `...rest` | `TextareaHTMLAttributes` | `readOnly`, `aria-invalid`, `maxLength` pass through. |

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div class="kw-specimen-row">
  <label class="kw-field"><span class="kw-field__row"><span class="kw-label">Logline</span><span class="kw-count">27 words</span></span><textarea class="kw-textarea kw-textarea--logline" rows="4">An editor alone in a night suite finds a frame in the rushes that nobody shot, and has until morning to learn who put it there.</textarea><span class="kw-hint">One or two sentences. Kwark never scores it.</span></label>
  <label class="kw-field"><span class="kw-label">Notes for wardrobe</span><textarea class="kw-textarea" rows="3">Bring the grey cardigan from Scene 9. Sleeves pushed up. It gets wet in Scene 14, so two of them.</textarea></label>
</div>
<div class="kw-specimen-row">
  <label class="kw-field"><span class="kw-field__row"><span class="kw-label">Pitch line for the festival form</span><span class="kw-count kw-count--over">312 of 300 characters</span></span><textarea class="kw-textarea" rows="5" aria-invalid="true">An editor alone in a night suite finds a frame in the rushes that nobody shot. As she traces it back through every hard drive and every crew member, the frame starts to appear in footage from days before the shoot began, and she has until morning to learn who put it there.</textarea><span class="kw-error" 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>The festival form takes 300 characters. Everything is kept here; trim it to fit.</span></label>
  <label class="kw-field"><span class="kw-label">Director’s note</span><textarea class="kw-textarea" rows="2" readonly>Keep the suite dark; the only light is the monitor.</textarea><span class="kw-hint">View only. Mira Rao wrote this.</span></label>
</div>
```

## Accessibility

- A visible `<label>`; the count and hint are tied with `aria-describedby`.
- The count updates silently; announce only when a limit is crossed, once.
- Do not trap Tab: Tab leaves the field, it never inserts a tab character.
- Never use `maxLength` to enforce an external limit; it drops text without telling anyone.

## For agents

### Rules

- **Never** use a textarea for screenplay text; use the editor.
- **Always** keep the height a person has set.
- **Never** truncate or refuse text at a limit; show the count, keep everything and say what the limit is for.
- **Never** score, grade or suggest edits to a logline; show its length only (Decision 0002).
- **Must** keep resize vertical only.

### AI readiness test

**Task:** Add a logline and a notes field to the project overview.

**Give the agent:** Textarea, Text input, Decision 0002.

**Constraint:** Plain text only; a festival form elsewhere has a 300-character limit.

**A reliable answer:**
- Visible labels
- Word count for the logline, no score
- Over-limit keeps the text and explains
- Vertical resize
- No Save button
