# Patterns

> How Kwark solves the problems every screen meets, from saving and sync to sharing by film role, each grounded in a decision and shown in real Kwark UI.

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

## What a pattern is here

A component is a part: a button, a sheet, a toast. A pattern is how parts work together to solve a problem a person meets again and again: their words not reaching the cloud, a screen with nothing on it yet, a producer who needs the call sheet as a PDF. Each pattern below starts with the problem as a writer or a crew member meets it, gives Kwark's answer and the decision behind it, and ends with a test an agent can be held to.

Three things are true of every pattern:

- **The work comes first.** Nothing competes with the page while someone writes. Chrome steps back; the script does not.
- **The work is never at risk, and never looks it.** Every state says whether the work is safe, in plain words.
- **Nothing is compulsory.** Structure, rhythm, tours and targets are optional and can be switched off.

## Saving, safety and state

- [Saving and sync](https://kwark.space/designSystem/patterns/saving-and-sync.md): Kwark saves as you write, keeps every change on the device until the cloud has it, never lets one device silently overwrite another, and says where the work is in one calm word.
- [Errors](https://kwark.space/designSystem/patterns/errors.md): When something goes wrong, Kwark says the state of the work first, then what happened and what to do, in one calm sentence, and never shows raw system text.
- [Loading](https://kwark.space/designSystem/patterns/loading.md): Kwark keeps the page's frame steady while work arrives, says what it is opening in plain words, shows progress only when it is long enough to matter, and never lets a half-loaded screen save over real work.
- [Destructive actions](https://kwark.space/designSystem/patterns/destructive-actions.md): Kwark prefers Undo to "Are you sure?", keeps deleted stories in the trash for 30 days, and asks only before something that cannot be undone or that changes what other people can see, naming exactly what will go.
- [Notifications](https://kwark.space/designSystem/patterns/notifications.md): Kwark tells people only what they need to act on or would want to know, in the place it concerns, quietly; it sends no email, has no notification feed, and never exists to bring people back.

## Finding your way

- [Navigation](https://kwark.space/designSystem/patterns/navigation.md): Kwark has one ladder (Home, project, phase, module, page), one breadcrumb that switches between neighbours, two phases named Write and Prepare to shoot, and a project home that orients before it sends you anywhere.
- [Phones](https://kwark.space/designSystem/patterns/phones.md): On a phone Kwark gives the screen to the work: one 44px header line, content by the first fifth of the screen, one floating button for comments, notes and account, rows without buttons, and thumb-sized targets everywhere.
- [Menus and shortcuts](https://kwark.space/designSystem/patterns/menus-and-shortcuts.md): The screenplay has five desktop-grade menus (File, Edit, Format, View, Help) with one home for every command, real shortcuts shown beside them, switches for what stays on, and the same list as a drill-down sheet on a phone.
- [Search and filter](https://kwark.space/designSystem/patterns/search-and-filter.md): Kwark lets people find things the way they would say them, keeps filters visible and easy to clear, and folds find, filter and sort into one labelled control on a phone.
- [Settings](https://kwark.space/designSystem/patterns/settings.md): Anything chosen once and kept lives in one Settings window, grouped by what it changes, each row saying what it does and whether it is for this project or all your scripts; optional features start off, and every change applies at once.

## Starting and filling in

- [First run](https://kwark.space/designSystem/patterns/first-run.md): A new visitor's first frame says what Kwark does and offers one way to begin; no account is needed, a guest keeps their place through sign-in, and nothing about the first minutes counts, tours or nags.
- [Onboarding without teaching](https://kwark.space/designSystem/patterns/onboarding-without-teaching.md): Kwark helps people find its own controls when they look for them, through plain names, honest empty states, a sample film and an optional tour, and never teaches them how to write or make a film.
- [Empty states](https://kwark.space/designSystem/patterns/empty-states.md): An empty screen in Kwark says what goes here, where it comes from, and the one way to fill it, without jokes, illustrations, coaching or guilt.
- [Forms](https://kwark.space/designSystem/patterns/forms.md): 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.

## Working with others

- [Sharing and roles](https://kwark.space/designSystem/patterns/sharing-and-roles.md): Sharing in Kwark is one panel, by film role, safe by default. New people are Readers, the request link is off, every person is named and removable, and because Kwark sends no email the owner sends the invite themselves.
- [Collaboration](https://kwark.space/designSystem/patterns/collaboration.md): Kwark shows who else is here only when someone is, draws their pointer where it lands on the page, keeps comments anchored to what they are about, and never lets two sessions silently overwrite each other.

## Making things

- [Print and export](https://kwark.space/designSystem/patterns/print-and-export.md): Everything a crew works from prints as the paper they already use and exports as structured data from the same copy; call sheets issue as numbered, frozen revisions; scripts in Indian languages print with correctly shaped text.
- [AI assistance](https://kwark.space/designSystem/patterns/ai-assistance.md): How machine help works in Kwark, step by step. A machine may measure the work, find things in it, carry it into production, move the writer's own words, convert how they are typed, read it aloud, or prepare it for a tool the person chooses. Every proposal is marked, sourced, offered one at a time, undoable and never a judgement.

## How to read a pattern page

| Section | Answers |
|---|---|
| The problem | What the person meets, in their situation |
| Kwark's answer | What Kwark does, and the decision record it comes from |
| Anatomy | The parts and what each means |
| Rules | **Must**, **Never** and **Always** bullets an agent can check |
| Phone and desktop | What changes under 768 wide and on a phone held sideways |
| Writing | The exact words, from the app |
| Accessibility | Roles, focus, announcements, targets |
| Demo | Live HTML in Kwark's classes, light and dark |
| AI readiness test | A task an agent should be able to do from the page alone |

> **For agents:** Before you design a flow in Kwark, find the pattern that covers it here and follow it. If two patterns seem to conflict, the one closer to the work being safe wins; then ask.

## AI readiness test

**Task:** A module shows "Sync failed" in red when offline. Fix it.

**Give the agent:** This page, Saving and sync, Errors.

**Constraint:** Use the app's own words.

**A reliable answer:**
- Replaces it with a state that says the work is safe ("Saved on this device")
- Uses amber with a word, never red alone, because nothing is lost
- Offers a next step only if the person can act (Retry, Backup)
- Removes the message when the state is ordinary
