# Forms

> Kwark forms ask for as little as possible, let everything wait, save as you go where they can, and say where each answer will end up.

Source: https://kwark.space/designSystem/patterns/forms

## The problem

A writer has an idea on the bus and opens Kwark to catch it. If the first thing she meets is a form asking for a title, a logline, a genre, a format and a target length, the idea goes while she decides on a genre. Later, on set, a 2nd AD is filling in a call sheet with one thumb while someone talks to him; a form that clears itself after a bad date, or hides why a button is disabled, costs him minutes he does not have.

Forms are where software most often asks people to do its work. Kwark's people are part-time filmmakers with little time and, at the start, a lot of doubt.

## Kwark's answer

### Ask for nothing that can wait

The new-project form is the model. Its heading is "Make room for a story" and its line says "Start with an idea, a title, or nothing at all. Everything here can wait." Every field is optional: a working title (placeholder "Untitled Story"), a writing format (Feature film, Short film, Series, or **Choose later**), genres, a colour for this story, and a note to begin with ("A character, a moment, a question you keep coming back to..."). The button says **Start writing**. Editing the same project later says "Change whatever you need. Your writing stays with you." and **Save changes**.

This follows the mission's first promise: the way to begin is obvious and one step away.

### Most of Kwark is not a form

A character page, a location, a call sheet, a budget line: these are documents, not forms. They save as you type, with the state in one word ("Saving…", "Saved on this device"). There is no Submit. A form with a final button is used only when the action is a single event that creates or changes something as a whole: starting a project, inviting people, issuing a revision, signing in.

### Say where the answer goes

A hint under a field says where the value will appear, never why it matters to the story (Decision 0004). "Appears on every call sheet that uses this location." "Goes to the budget for every day this location is booked." That is the field's artefact, and it is the honest reason to fill it in.

## Anatomy

| Part | Rule |
|---|---|
| Label | Above the field, sentence case, a plain noun: "Working title", "Call time", "Cost per day". Never uppercase. |
| Optional marker | "Optional" in quiet text beside the label, when most fields are required. In Kwark most fields are optional, so mark the rare required one instead. |
| Field | `kw-input`, `kw-select`, `kw-textarea`; 36px on desktop, 44px on phones; strong line border (3:1). |
| Hint | Where the value ends up, or the format expected ("HH:MM"). One line. |
| Error | Under the field, what to change: "Choose a date after today, or choose No end date." |
| Actions | Cancel quiet on the left of the pair, the primary action named for what it does on the right. |
| Disabled reason | Written on the page beside a disabled action, not only in a tooltip. |

## Validation

- **Validate on leaving the field or on submit**, not on every key. A writer typing a date should not be told it is wrong after the first digit.
- **Keep everything typed.** Never clear a field because another one failed.
- **Say what to change**, in the person's terms, in one sentence.
- **Accept the forms people use.** "6:30", "06:30" and "6.30" are the same call time. "Mira, Dev" splits into two names.
- **Check what can only be checked once**, gently, at the action: before issuing a call sheet with no hospital, a calm notice ("Location to be confirmed. Add it before issuing the call sheet.") rather than a blocked button with no reason.
- **Never trust the label.** Sharing roles are a label over the per-module map; access is checked on the map, not on the word.

## Real copy from the app

- New project: "Make room for a story" · "Start with an idea, a title, or nothing at all. Everything here can wait." · **Start writing** · "You can change these anytime."
- Failure: "Your story could not be saved. Please try again."
- Sharing: placeholder "Add people by email"; hint "Type the Google email of the person you want to add."; "That is your own address. You already own this project."; "Choose a date after today, or choose No end date."
- Settings rows: a title and a line of detail, for example **Suggest names**, "Characters offered as a cue is typed, from the cast and the script."
- Search fields: "Find a story…", "Search the screenplay".
- Export: "Recipient or DO NOT DISTRIBUTE" for the watermark field; "Character names, separated by commas".

## Rules

- **Must** label every field with a visible label above it, in sentence case, linked with `for` or by wrapping.
- **Must** keep every typed value when validation fails, a retry is needed, or the person navigates back.
- **Must** put the reason for a disabled action on the page.
- **Must** use 44px fields and 16px input text on phones so iOS does not zoom.
- **Never** use a placeholder as the label. A placeholder is an example ("Untitled Story"), and it disappears.
- **Never** use uppercase or letter-spaced labels. The legacy `Input` in `components/ui/Input.tsx` still renders them; the system does not.
- **Never** ask for something Kwark can work out from the script (scene count, cast, locations).
- **Never** ask a writer for a production fact in the writing phase. A character's age belongs to the story; union status belongs to Cast and crew, and only where the country has one.
- **Always** name the primary button for what happens: **Start writing**, **Save changes**, **Issue Rev 3**, never **Submit** or **OK**.
- **Always** let Enter submit a single-line form, and let Escape cancel a dialog form without losing what was typed if it was saved as a draft.

## Edge cases

- **Indian scripts in a field.** Names typed in Tamil or Devanagari must be stored and shown as typed; never upper-case them, never strip combining marks, and set Indic lines a little smaller where they stack (as the script does at 0.9×).
- **Paste of a whole list.** "Mira, Dev, Asha" into a cast field becomes three people, with a review step if any name is new.
- **Two people editing the same record.** A document-style form saves per field, so two edits to different fields both survive; see [Saving and sync](https://kwark.space/designSystem/patterns/saving-and-sync.md).
- **A long form on a phone.** Group it with headings, let each group collapse, and keep the primary action reachable without scrolling past the keyboard.
- **Country-specific fields.** GST, union rules and paperwork follow a setting, not a flat assumption (the audit replaced a flat 18% GST with a setting).

## Phone and desktop

On a phone a form is a full-screen sheet with the one-line header: back, the title, and the primary action on the right only if it is short ("Save"). Fields are one column, 44px, labels above. The keyboard type matches the field (`type="email"`, `inputmode="numeric"` for amounts, `type="time"` for call times). On desktop, short forms sit in a dialog no wider than 480px; long ones are documents on the page. Two-column layouts only for pairs a person reads together (Start and End, Day and Night).

## Accessibility

- Labels are programmatic; hints and errors are linked with `aria-describedby`.
- An invalid field has `aria-invalid="true"` and the error says what to change. On submit, focus moves to the first invalid field.
- Groups of radios or checkboxes sit in a `fieldset` with a `legend` ("Writing format").
- Required fields, if any, say "Required" in words, not only an asterisk.
- Nothing is conveyed by placeholder alone, which has low contrast by design.

**Do:** **Working title** (Optional), placeholder "Untitled Story", and **Start writing** with nothing else required.

**Don't:** A required Title, Logline, Genre and Target length before the writer can see a page.

**Do:** **Cost per day**, hint "Goes to the budget for every day this location is booked."

**Don't:** **COST/DAY** in letter-spaced capitals, with a placeholder as the only label.

**Do:** **Issue Rev 3** disabled, with "Add a hospital to the safety block first." written beside it.

**Don't:** A greyed button whose reason appears only on hover.

## Demo

```html
<div class="kw-card" style="width:100%;max-width:440px;display:grid;gap:14px">
<strong style="font:600 var(--k-fs-head)/1.25 var(--k-font-display)">Make room for a story</strong>
<span class="kw-row__meta">Start with an idea, a title, or nothing at all. Everything here can wait.</span>
<label class="kw-field"><span class="kw-label">Working title</span><input class="kw-input" placeholder="Untitled Story"></label>
<fieldset style="border:0;padding:0;margin:0;display:grid;gap:8px"><legend class="kw-label" style="margin-bottom:6px">Writing format</legend>
<div class="kw-segment" role="group" aria-label="Writing format"><button type="button" aria-pressed="true">Feature film</button><button type="button" aria-pressed="false">Short film</button><button type="button" aria-pressed="false">Series</button></div>
<span class="kw-hint">You can change these anytime.</span></fieldset>
<label class="kw-field"><span class="kw-label">A note to begin with</span><textarea class="kw-textarea" placeholder="A character, a moment, a question you keep coming back to..."></textarea></label>
<div style="display:flex;justify-content:flex-end;gap:8px"><button class="kw-button kw-button--quiet" type="button">Cancel</button><button class="kw-button kw-button--primary" type="button">Start writing</button></div>
</div>
<div class="kw-card" style="width:100%;max-width:440px;display:grid;gap:10px">
<label class="kw-field"><span class="kw-label">Cost per day</span><input class="kw-input" inputmode="numeric" value="₹ 12,000" aria-describedby="hint-cost"><span class="kw-hint" id="hint-cost">Goes to the budget for every day this location is booked.</span></label>
<label class="kw-field"><span class="kw-label">Crew call</span><input class="kw-input" value="6.30" aria-describedby="hint-call"><span class="kw-hint" id="hint-call">Read as 06:30. Appears at the top of the call sheet.</span></label>
</div>
```

## Related

[Text input](https://kwark.space/designSystem/components/text-input.md), [Textarea](https://kwark.space/designSystem/components/textarea.md), [Select](https://kwark.space/designSystem/components/select.md), [Segmented control](https://kwark.space/designSystem/components/segmented-control.md), [Errors](https://kwark.space/designSystem/patterns/errors.md), [Saving and sync](https://kwark.space/designSystem/patterns/saving-and-sync.md), [Settings](https://kwark.space/designSystem/patterns/settings.md).

## AI readiness test

**Task:** Build the "Add a location" form for the production office.

**Give the agent:** This page, Decision 0005, Decision 0022, Errors.

**Constraint:** Save as you go; phone first.

**A reliable answer:**
- Only the name is needed to create it
- everything else can wait
- Hints say where each value goes (call sheet, budget, map)
- No Submit: a document that saves per field, with the sync word
- 44px fields, sentence-case labels above, numeric keyboard for cost
- Reason written beside anything disabled
