# Kwark Design System — full text # AGENTS.md — Kwark Design System You are writing interface code or design for Kwark, or for a product that uses the Kwark Design System. Follow these rules. When something you need is not covered, say so and ask; do not invent a token, a component or a rule. Docs: https://kwark.space/designSystem (every page links to a Markdown twin). Tokens: `tokens.json` and `kwark.css`. Components: `components.json`. ## The five rules that matter most 1. **Use the role, never the value.** Colours, fonts, sizes, radii, spacing and durations come from `--k-*` tokens. A hex code, `px` font size or font name inside a component is a bug. 2. **Use the shared component before writing a new one.** Check `components.json`. If two things look different but do the same job, one of them is wrong. 3. **A control says what it is, with a word.** Icon-only only for universal glyphs (back, close, more, add, search), and always with an accessible name that includes its object. 4. **Machines carry; people write.** Never score, grade, judge or rewrite a person's story (Decision 0002). A machine may only find, move, convert or carry the writer's own words (a prop found in the script, a scene heading from their outline beat, a transliteration). Mark anything it proposes with a revision mark until a person accepts or edits it, and never save it into the work on its own. 5. **Calm, flat, legible.** No glows, gradients, sparkles or decorative shadows. Depth is a line and a step in tone. Nothing under 12px on a phone, nothing under 11px anywhere. ## Colour - **Must** use `--k-bg`, `--k-surface`, `--k-raise`, `--k-line`, `--k-text`, `--k-text-2`, `--k-accent`, `--k-on-accent` and the status pairs (`--k-ok`/`--k-ok-bg`, `--k-info`, `--k-warn`, `--k-danger`). - **Must** reach 4.5:1 for text and 3:1 for icons and control borders, in light, dark and every writing room. - **Never** carry meaning by colour alone. **Never** use red for anything that does not block work. - Inside the screenplay editor the roles follow the room (`data-room`). Do not hard-code editor colours. ## Type - UI: `--k-font-ui` (Poppins). Headings: `--k-font-display`. Script: `--k-font-screenplay` (Courier Prime, 12pt geometry). Code and numbers in tables: `--k-font-mono`. - Sizes: `--k-fs-meta` 12, `--k-fs-body` 14, `--k-fs-title` 16, `--k-fs-head` 20, `--k-fs-display` 28, `--k-fs-hero` (desktop only). - Sentence case everywhere. No all-caps labels except screenplay elements that are capitalised by convention. ## Space, shape, depth - Spacing: 4, 8, 12, 16, 24, 32 (`--k-space-1…6`). Phone gutter 16. - Radius: 6 controls, 10 cards, 14 sheets and dialogs, 999 pills. - Elevation: resting surfaces are flat. Only things that float above the page (menus, dialogs, toasts, the phone dial) get `--k-shadow-pop`. - Tap targets: 44px on phones (`--k-tap`). ## Phones (≤767px and sideways phones) - **Must** use one 44px header line: back, one-word title, at most two labelled actions, and "Menu ▾". - **Must** start content by about y = 200. No subtitles, breadcrumbs, explanatory sentences or rows of chips above the fold. - Rows have no buttons; actions live in the row's ⋯ sheet. Menus become bottom sheets that drill down one page at a time. - One floating control per screen. Reserve `--k-fab-slot` at the foot of the page. ## Writing - Buttons: verb + object, sentence case. "Save scene", never "Submit" or "OK". The same word through the flow: Publish → Published. - Errors say what happened and how to fix it, in the interface's voice. No apologies, no blame, no exclamation marks. - Empty states: what goes here, why, and one action. No jokes or illustrations. - Prefer Undo over "Are you sure?". Confirm only what cannot be undone or affects other people. ## Motion - `--k-dur-1` 120ms (hover, press), `--k-dur-2` 200ms (open, toggle), `--k-dur-3` 320ms (panels). Ease out with `--k-ease`. - Motion answers an action. No ambient animation in the app. Everything stops under `prefers-reduced-motion`. ## Accessibility - Native elements first: `button`, `a`, `input`, `select`, `dialog`, `details`. - Visible focus on everything (2px `--k-focus`, 2px offset). Never remove outlines without a replacement. - Every dialog and sheet returns focus to its trigger. Every menu closes on Escape. ## Before you finish - Search your diff for `#`, `rgb(`, `px` font sizes and font names. Replace them with tokens. - Check the phone layout at 375px and 320px. - If you changed a rule, add a decision record (docs/ux/decisions) with the reason. # About the system > What the Kwark Design System is, who it is for, what is inside, how it is versioned and what the status labels on each page mean. Source: https://kwark.space/designSystem/about ## What it is The Kwark Design System is the set of rules, parts and patterns that Kwark is built from. Kwark is a story workspace for filmmakers: a screenplay editor, outline, characters, research, breakdown, shots, storyboards, schedule, call sheets and budget, shared with a crew by film role. The system is not a theme laid over the app. It is written from the app: every component on this site is drawn from Kwark's own source, with the same geometry, type, colours, states and words. Where a rule exists, it comes from a decision Kwark has made and recorded, and the page cites the decision by number ("Decision 0016"). It is written once and published twice: as pages for people, and as plain markdown, tokens and JSON for the agents that build with them. See [For agents](https://kwark.space/designSystem/agents/index.md). ## Who it is for - **Kwark's own team.** Designers, engineers and the agents working beside them. This is the reference for every screen in the app. - **Teams building a filmmaking or creative app.** A script tool, an editor, a storyboard, a scheduler, a sound or grading tool, a production office. Creative tools share problems that general design systems do not cover: a person's work on the page, timelines and playheads, the printed artefact, writing rooms, offline, machine suggestions that must not take over authorship. The [Creative app kits](https://kwark.space/designSystem/kits.md) are written for you. - **People building with AI.** If you describe screens to Claude, Cursor, Codex or Gemini and let them write the code, the system gives them something specific to follow instead of a generic default. Start with [For agents](https://kwark.space/designSystem/agents/index.md). > The system is opinionated because Kwark is. It assumes a person's work is private and theirs, that the interface never judges it, and that structure is offered, never imposed. If your product needs streaks, rankings or a machine that grades people, this system will fight you. ## What is inside | Section | What you get | |---|---| | [Foundations](https://kwark.space/designSystem/foundations.md) | Colour, type, space, radius, elevation, layout, motion, icons; principles, accessibility, writing rooms, Indian scripts, content and UX writing, AI and authorship, data visualisation. | | [Components](https://kwark.space/designSystem/components.md) | Each part with live HTML, the React import when it is in the app, tokens, anatomy, accessibility, rules and an AI readiness test. | | [Patterns](https://kwark.space/designSystem/patterns.md) | How parts combine for a job: saving and sync, errors, empty states, phones, menus and shortcuts, sharing by role, print and export, and more. | | [Creative app kits](https://kwark.space/designSystem/kits.md) | Starting points for screenwriting, editing, storyboards and shots, scheduling and call sheets, sound, grading, a production office, or any creative app. | | [Kwark method](https://kwark.space/designSystem/method.md) | How Kwark decides what to build: UX before build, decision records, competitors are the floor, structure not teaching, review. | | [For agents](https://kwark.space/designSystem/agents/index.md) | llms.txt, markdown twins, AGENTS.md, tokens.json, components.json, an MCP server, downloadable skills, prompts and readiness tests. | | `kwark.css` | Tokens and framework-free component styles in one file. See [Developing](https://kwark.space/designSystem/developing.md). | ## Status labels Every component page carries one label under its title. The label is about Kwark, not about quality: a "Ready for Kwark" part is specified as carefully as one in the app. | Label | What it means | What you can rely on | |---|---|---| | **In the app** | The component is in Kwark's source today. The page gives its real React import and props. | It ships. The HTML and CSS here reproduce it; the React component is the source of truth. | | **Ready for Kwark** | Kwark does not have this part yet. It is designed to the same tokens, corners, type and restraint, so it can be built without new decisions. | The spec, the HTML and the CSS. There is no React component yet; build it from the spec. | | **New** | Added or changed substantially in this release. Shown in the side navigation too. | Read it again even if you knew the old version. | | **Planned** | Named and scoped, not yet specified. | Nothing to build from yet. | > **For agents:** Treat "In the app" as the only label that means code exists in Kwark. For "Ready for Kwark", use the kw- HTML and CSS from the page and say in your answer that no React component exists yet. Never import a component that the page does not list. ## How it is versioned The system has one version number for everything on this site: pages, `kwark.css`, `tokens.json`, `components.json`, the MCP server and the skills. The number is on [Releases](https://kwark.space/designSystem/releases.md), with what changed. - **A major version** (4.0) changes the way the system is built or published, or removes or renames tokens or components. Expect to update code. - **A minor version** (4.1) adds components, patterns, tokens or rules without breaking what exists. - **A fix** corrects a value, a typo or a spec that did not match the app. Token names do not change inside a major version. If a token's value changes (a contrast fix, say), the release notes name it. ## Where it comes from The source is in the Kwark repository: prose in `design-system/content/`, components in `design-system/components*.mjs`, styles in `design-system/css/`. One build (`node design-system/build.mjs`) writes every HTML page, every markdown twin, `llms.txt`, `llms-full.txt`, `tokens.json`, `components.json`, `search.json` and `kwark.css`. A page and its markdown twin cannot drift apart because they are written from the same file in the same run. ## AI readiness test **Task:** Explain to a new engineer which components on this site they can import in Kwark today, and what to do with the others. **Give the agent:** This page, components.json. **Constraint:** Name only components whose status is "In the app" as importable. No invented import paths. **A reliable answer:** - Separates In the app from Ready for Kwark - Gives the import path only from the component page or components.json - Says Ready for Kwark parts are built from the kw- HTML and CSS - Mentions that New is about the release, not about whether code exists --- # AI context files > The files an agent can load - llms.txt, llms-full.txt, the markdown twins, AGENTS.md, tokens.json and components.json - what each is for, how to load it, and which one to use for which task. Source: https://kwark.space/designSystem/agents/ai-context ## The files All of them are generated by the same build as the pages, so none of them can fall behind the site. | File | What it is | Load it when | |---|---|---| | [`AGENTS.md`](https://kwark.space/designSystem/AGENTS.md) | The rules, in one short file: colour, type, space, phones, writing, motion, accessibility, and the checks before you finish. | Always. It is the first thing any agent writing Kwark UI reads. | | [`llms.txt`](https://kwark.space/designSystem/llms.txt) | The map: every page with its one-line summary and the URL of its markdown twin. | The agent needs to find the right page. | | Markdown twins | Every page as clean markdown, at the page's URL plus `.md`. Live demos become HTML code blocks; do and don't pairs become two labelled lines; swatches become a table with light and dark values. | The task touches that page. Load the few pages the task needs. | | [`components.json`](https://kwark.space/designSystem/components.json) | Every component: name, slug, summary, status, React import and props when it is in the app, the HTML, the tokens it uses and its rules. | The agent is building UI and must use real parts. | | [`tokens.json`](https://kwark.space/designSystem/tokens.json) | Every token as DTCG 2025.10 values, with exact CSS in the org.kwark.css extension: `light`, `dark`, and `rooms` for the five writing rooms. | The agent needs values: generating a native theme, checking a contrast, mapping another system's tokens. | | [`llms-full.txt`](https://kwark.space/designSystem/llms-full.txt) | `AGENTS.md` plus every page's markdown in one file. | A large-context review of the whole system, or offline use. Not for everyday work. | | `search.json` | Title, summary, group and keywords of every page. The site's search and the MCP server use it. | You are building a tool, not prompting. | | [`kwark.css`](https://kwark.space/designSystem/kwark.css) | The tokens and the component styles. | The agent is writing HTML that must render. | ## Which file for which task Load the least that answers the question. A long context the agent does not need makes its answer worse, not better: the rules that matter get diluted by pages that do not. | Task | Load | |---|---| | Build or change a screen | `AGENTS.md` + the `.md` of each component you use + the pattern page if one applies (saving, errors, empty states, phones) | | Write or review UX copy | `AGENTS.md` + `foundations/ux-writing.md` + the pattern page for that moment | | Review a diff | `AGENTS.md` + the pages for every part the diff touches; with the MCP server, `audit_code` on each file | | Phone layout | `AGENTS.md` + `patterns/phones.md` + `components/page-header.md` + `components/sheet.md` | | Anything inside the screenplay editor | add `foundations/rooms.md` | | Anything a machine proposes or writes | add `foundations/ai-and-authorship.md` and `components/revision-mark.md` | | Generate a native or Tailwind theme | `tokens.json` only | | "Which component should I use for…" | `llms.txt`, then the page it points to; or `search_docs` with the MCP server | | Audit the whole system, or write a guide | `llms-full.txt`, in a model with a large context window | > **For agents:** Load AGENTS.md first. Then load only the markdown twins the task touches. Do not load llms-full.txt for a single screen. If a page you need is not listed in llms.txt, say so instead of guessing what it would say. ## Token budget A rough rule: one token is about four characters of English. Check a file's size before loading it whole: ```bash curl -s https://kwark.space/designSystem/llms-full.txt | wc -c ``` - `AGENTS.md` is short: about a thousand tokens. It fits in every conversation. - `llms.txt` is a few thousand tokens: one line per page. - A component or pattern twin is usually between one and five thousand tokens. - `llms-full.txt` grows with the site and is far larger than any single task needs. Use it only where the whole system is the subject. - `tokens.json` and `components.json` are dense; ask for one component (`get_component`) or a filtered set of tokens (`get_tokens`) through the MCP server rather than loading the whole file. ## How to load them - **Paste.** Open the page, switch to **Agent**, press **Copy markdown**, paste it into the chat. - **By URL.** Agents that can fetch (Claude Code, Codex, Cursor) can be given the `.md` URL directly: "Read https://kwark.space/designSystem/patterns/errors.md first." - **In the repository.** Copy `AGENTS.md` into the root of your repository (Codex and others read it automatically), or reference it from `CLAUDE.md`, `.cursor/rules/` or `GEMINI.md`. - **Through MCP.** The [MCP server](https://kwark.space/designSystem/agents/mcp.md) serves every file on demand: `get_page` for a twin, `get_component`, `get_tokens`, `search_docs`. ## What the twins contain A twin is the page, not a summary. It starts with the title, the summary and the source URL, then the content in order. Things built for the eye are converted: - A live demo becomes an `html` code block that renders with `kwark.css`. - A do and don't pair becomes `**Do:**` and `**Don't:**` lines. - A swatch list becomes a table of token, name, light value, dark value and use. - A readiness test becomes the task, the context to give, the constraint and the list of things a reliable answer contains. - Links between pages point to the other pages' twins, so an agent following a link stays in markdown. ## AI readiness test **Task:** An agent is asked to build the phone version of the Characters list. Say exactly which files it should load and in what order, and which it should not. **Give the agent:** This page, llms.txt. **Constraint:** Keep the context under ten thousand tokens. **A reliable answer:** - AGENTS.md first - patterns/phones.md, components/page-header.md, components/list-row.md and components/sheet.md - Not llms-full.txt - Uses llms.txt or search_docs to find any page it is unsure of - Says it will check the layout at 375 and 320 --- # Design-to-code handoff > How Kwark hands a design to whoever builds it, a person or an agent - a spec that names components and tokens, covers phone and desktop, every state, every word, accessibility and edge cases, with a template to download. Source: https://kwark.space/designSystem/agents/handoff ## What a handoff is for A handoff spec lets someone build a screen without asking a question and without making a decision the designer did not make. In Kwark it comes after the journey and the wireframe have been agreed ([UX before build](https://kwark.space/designSystem/method/ux-before-build.md)), and it is the same document whether the builder is an engineer or an agent. The difference from a typical handoff is that a Kwark spec rarely contains pixels. It names parts and roles: "Button, primary", "`--k-space-4`", "`--k-fs-title`". The component pages already hold the geometry. A spec that repeats it can only disagree with it. **[Download the template (markdown)](https://kwark.space/designSystem/skills/kwark-handoff/template.md)** ## What goes in it ### The person and the problem One sentence: who, in what situation, what gets in their way. Then the decision record it follows, or the draft of a new one. A builder who knows why makes better calls on the details the spec missed. ### The journey Where the person comes from, each step, what they see, what they do, how they get back to the work. A spec without the journey produces a screen that works alone and breaks the flow it sits in. ### Layout, phone and desktop separately - **Desktop at 1440** (and 1024): regions and the component for each. - **Phone at 375** (and 320): the one header line (back, a one-word title, at most two labelled actions, Menu ▾), what fills the first 200px, the one floating control if any, rows without buttons. A phone layout is not the desktop squeezed. It is a different arrangement of the same content: see [Phones](https://kwark.space/designSystem/patterns/phones.md) and Decision 0016. ### Parts and tokens A table of each part, its component and variant, and the tokens it uses. If no component fits, write "new component" and describe it with tokens, then propose it ([Contributing](https://kwark.space/designSystem/contributing.md)). ### Every state This is where specs most often stop short, and where agents most often invent. List them all: default, hover, focus, pressed, disabled (and why), loading, empty, error, offline, read-only for a shared viewer, long text, a script in an Indian language. Kwark's own save word is a good example of how complete this has to be. The screenplay's corner pill has nine states, each with a fixed word, and the spec says which ones fade: | State | Word | Stays or fades | |---|---|---| | Opening | Loading… | stays | | Not on this device yet | Not downloaded | stays | | In step with the cloud | Up to date | fades after 2.6 seconds | | Typing | Edited | stays | | Writing to storage | Saving… | stays | | Stored | Saved | fades after 2.6 seconds | | Stored here, not yet in the cloud | Saved on this device | stays | | Not stored | Not saved | stays | | Another session changed it | Changed elsewhere | stays | Good news is worth a glance; anything the writer must act on stays visible (element register, Decision 0013). ### Copy Every string exactly as it will ship, in Kwark's voice. No lorem ipsum and no "TBD": the words decide the layout as much as the boxes do. See [UX writing](https://kwark.space/designSystem/foundations/ux-writing.md). ### Saving, data and offline What is saved, when, where (device, cloud), the word the person sees, and what happens if it fails halfway. Kwark runs on a free database tier, so the spec also says how many reads and writes an action costs and flags any list or listener with no limit. ### Accessibility Keyboard path and shortcuts (⌘ on Mac, Ctrl elsewhere), the accessible name of every control without a visible word, focus order, where focus returns when a dialog or sheet closes, contrast in light, dark and the writing rooms, and what happens under reduced motion. ### Edge cases and out of scope The cases with their expected behaviour, and what this deliberately does not do, so nobody builds it by accident. ### Open questions Anything undecided, with the options and a recommendation, and who decides. A builder never fills a gap silently. **Do:** "Empty: 'No scenes yet. Scenes appear here as you write headings.' One action: Write the first scene (Button, primary). Phone: same words, button full width." **Don't:** "Empty state: TBD." or "Show a nice illustration and a call to action." ## Handing off to an agent Everything above, plus three things agents need more than people do: - **The files to load.** Name the `.md` twins of every component and pattern the spec uses, and `AGENTS.md`. See [AI context files](https://kwark.space/designSystem/agents/ai-context.md). - **The limits, before the task.** "Only --k-* tokens. Only components in components.json. Do not change the desktop layout." An agent reads constraints given after the task as afterthoughts. - **The checks it must run.** `audit_code` on each file if the [MCP server](https://kwark.space/designSystem/agents/mcp.md) is installed, screenshots at the four widths, and a list of what the system did not cover. The [kwark-handoff skill](https://kwark.space/designSystem/agents/skills.md) writes a spec in this shape from a design description. > **For agents:** When you receive a Kwark handoff spec: build exactly the states and strings listed; if one is missing, stop and ask rather than inventing it. Use the components named. If a part says "new component", build it with --k-* tokens only and say that it needs a component page. ## Acceptance checks The spec ends with the checks a reviewer will run, so the builder can run them first: - Tokens only: no hex, rgb, px font sizes or font names. - Shared components; every control has a word or a named icon; chevrons on things that open. - Screenshots at 1440, 768, 375 and 320, looked at. - Every listed state exists, with the listed words. - Keyboard and screen reader pass. - Decision record and element register updated. ## AI readiness test **Task:** Write the handoff spec for the "Issue call sheet" action, which locks a call sheet and gives it a revision number. **Give the agent:** This page, the template, Patterns: destructive actions, Patterns: phones. **Constraint:** Name components and tokens, no pixel values. Fill every section of the template. **A reliable answer:** - Starts with the person (the 1st AD) and the problem in one sentence - Gives phone and desktop separately - Lists states including offline and read-only - Writes the real copy (Issue call sheet, Issued, revision numbers) - Says what is saved and what happens if it fails halfway - Lists open questions instead of deciding them silently --- # MCP server > Install the Kwark design MCP server in Claude Code, Cursor, Codex or Gemini so an agent can search the docs, read any page, look up components and tokens, and audit its own code against the system. Source: https://kwark.space/designSystem/agents/mcp ## What it does The Model Context Protocol lets an agent call tools while it works. The Kwark server gives it five, so it can look things up when it needs them instead of carrying the whole system in its context: | Tool | What it returns | |---|---| | `search_docs` | Pages that match a query, with a snippet and the URL of each page's markdown twin. | | `get_page` | Any page as markdown. `"agents.md"` returns the rules; `"llms"` returns the map. | | `get_component` | A component's spec: status, React import and props when it is in the app, HTML, tokens and rules. `full: true` adds the whole page. | | `get_tokens` | Tokens matching part of a name, with light and dark values, and a writing room's value when asked. | | `audit_code` | Issues in a snippet of TSX, JSX, HTML or CSS: colour literals, px font sizes, font names, icon sizes off 14/16/20, icon-only buttons without an accessible name, buttons without `type`, clickable `div`s, glows, gradients and resting shadows. Each issue has its line and the fix. | It is one file with no dependencies. It needs Node 18 or later. ## Install Download the server: ```bash mkdir -p ~/.kwark && curl -fsSL https://kwark.space/designSystem/mcp/kwark-design-mcp.mjs -o ~/.kwark/kwark-design-mcp.mjs node ~/.kwark/kwark-design-mcp.mjs --self-test ``` The self-test checks the auditor and reads a page and the tokens, then prints where it read them from. ### Where it reads from 1. `KWARK_DS_DIR`, if set: a folder holding the built site, or a URL of one. 2. The built site beside the file. Inside the Kwark repository that is `public/designSystem/`, so the server always matches your local build. 3. Otherwise `https://kwark.space/designSystem`, fetched once per session and kept in memory. ### Claude Code From the project folder: ```bash claude mcp add kwark-design -- node ~/.kwark/kwark-design-mcp.mjs ``` Or commit it for the whole team in `.mcp.json` at the root of the repository: ```json { "mcpServers": { "kwark-design": { "command": "node", "args": ["/Users/you/.kwark/kwark-design-mcp.mjs"] } } } ``` Inside the Kwark repository itself, point at the copy that reads your local build: ```json { "mcpServers": { "kwark-design": { "command": "node", "args": ["/path/to/kwark/design-system/mcp/kwark-design-mcp.mjs"] } } } ``` Run `/mcp` in Claude Code to check that `kwark-design` is connected and lists five tools. ### Cursor In `.cursor/mcp.json` (this project) or `~/.cursor/mcp.json` (every project): ```json { "mcpServers": { "kwark-design": { "command": "node", "args": ["/Users/you/.kwark/kwark-design-mcp.mjs"] } } } ``` ### Codex In `~/.codex/config.toml`: ```toml [mcp_servers.kwark-design] command = "node" args = ["/Users/you/.kwark/kwark-design-mcp.mjs"] ``` ### Gemini CLI In `~/.gemini/settings.json`, or `.gemini/settings.json` in the project: ```json { "mcpServers": { "kwark-design": { "command": "node", "args": ["/Users/you/.kwark/kwark-design-mcp.mjs"] } } } ``` > Use an absolute path. Most clients do not expand `~` inside a JSON or TOML file. To read from your own build of the site instead, add `"env": { "KWARK_DS_DIR": "/path/to/public/designSystem" }` to the server's entry. ## Using it You rarely need to name the tools. Ask for the work and say the server is there: "Build the Scene notes panel with the Kwark system. Use the kwark-design tools to look up components and audit what you write." Agents follow the server's own instructions: read the rules, look up parts, check tokens, audit before finishing. Examples of what the agent sends, and what comes back: ```json { "name": "search_docs", "arguments": { "query": "sync error copy", "limit": 3 } } ``` Returns the best matches, such as Saving and sync and Errors, each with a snippet and its `.md` URL. ```json { "name": "get_tokens", "arguments": { "name": "accent", "room": "paper" } } ``` Returns `--k-accent` with its light value, its dark value and, for Paper, the room's pencil colour, plus `--k-accent-soft` and `--k-on-accent`. ```json { "name": "get_component", "arguments": { "name": "Breadcrumb" } } ``` Returns the Breadcrumb spec with `import { Breadcrumb } from '@/components/ui/Breadcrumb'`, its props, its HTML, tokens and rules. ```json { "name": "audit_code", "arguments": { "code": "
Scene 12
" } } ``` Returns three issues on line 1: a clickable `div`, a colour literal and a px font size, each with the fix. ## What it does not do - `audit_code` reads lines and simple tag structure, not a syntax tree. It misses things a person would see (a layout that breaks at 320, a word that judges the writer) and can flag a rare false positive. A clean audit is not a review: see [Readiness tests](https://kwark.space/designSystem/agents/readiness.md) and [Contributing](https://kwark.space/designSystem/contributing.md). - It does not write files. It only reads the system and reports. - It sends nothing anywhere. Reading from `kwark.space` fetches public files only; the code you audit stays on your machine. ## For the Kwark repository The source is `design-system/mcp/kwark-design-mcp.mjs`. The built site serves a copy at `/designSystem/mcp/kwark-design-mcp.mjs`. Run `node design-system/mcp/kwark-design-mcp.mjs --self-test` after changing it. It replaces the v3 server in `scripts/kwark-design-mcp.mjs`; the tool names changed (see [Releases](https://kwark.space/designSystem/releases.md)). ## AI readiness test **Task:** Connect the Kwark MCP server to Cursor and Claude Code for a team repository, and show the first three tool calls an agent should make before building a dialog. **Give the agent:** This page. **Constraint:** Absolute paths. Only the five tools listed here. **A reliable answer:** - Downloads the file and runs --self-test - Gives .mcp.json and .cursor/mcp.json with command node and an absolute path - Calls get_page with agents.md first - Then get_component for dialog and get_tokens for what it needs - Ends with audit_code on the result --- # Prompt library > Copy-ready prompts for building with the Kwark system - a screen, a review, UX copy, a phone layout, a new component, a decision record and a readiness test - each with the context files it needs. Source: https://kwark.space/designSystem/agents/prompts ## How to use these Each prompt names the files to load. Replace the words in angle brackets. Paste the prompt as it is: the order of the sentences matters, because the agent reads the constraints before the task. If the [MCP server](https://kwark.space/designSystem/agents/mcp.md) is installed, the agent can fetch every file named here itself. If not, paste the `.md` twins or give their URLs. > These prompts ask for small, finished pieces of work. One screen, one review, one record. An agent asked for "the whole module" will make a hundred small decisions you did not see. ## Build a screen Context: `AGENTS.md`, the component pages for the parts, the pattern pages that apply. ```text Read https://kwark.space/designSystem/AGENTS.md first, then the component pages for every part you use (https://kwark.space/designSystem/components/.md) and https://kwark.space/designSystem/patterns/.md. Build for , who is . Rules: use only --k-* tokens and components listed in https://kwark.space/designSystem/components.json. Every control has a word, or an icon with an aria-label that names its object. Anything that opens something has a chevron. No glows, gradients or shadows on resting surfaces. Write every state: empty, loading, error, offline and read-only, and the case of a long scene heading ("INT. EDIT SUITE – NIGHT – CONTINUOUS"). When you finish, list the components and tokens you used, anything the system did not cover, and run audit_code on each file if you have the Kwark MCP server. ``` ## Review a diff against the system Context: `AGENTS.md`, the pages for the parts the diff touches, `foundations/principles.md`. ```text You are a review-only UI and UX supervisor for a product built on the Kwark Design System. Do not edit files. Read https://kwark.space/designSystem/AGENTS.md and https://kwark.space/designSystem/foundations/principles.md, then the component and pattern pages for every part this diff touches. Review . Check, in order: does anything judge, count or nag the person; is their work safe if this fails halfway; tokens only; shared components; a word on every control and chevrons on things that open; every state; phone layout at 375 and 320; keyboard, focus and accessible names; contrast in light, dark and the five writing rooms; copy in Kwark's voice. Report one finding per line: where, what is wrong, which rule or decision it breaks, and the smallest fix. Most serious first. Say what you could not check. ``` ## Write UX copy Context: `foundations/ux-writing.md`, `foundations/content.md`, the pattern page for the moment. ```text Read https://kwark.space/designSystem/foundations/ux-writing.md and https://kwark.space/designSystem/patterns/.md. Write the interface words for . The person is , and they are worried about . Sentence case. Buttons are verb + object. Say the state of the work first. No apologies, no blame, no exclamation marks, no hype words. Never judge the writing. Give the desktop copy and, where it must be shorter, the phone copy. After each string, one line on which rule it follows. ``` ## Make a phone layout Context: `AGENTS.md`, `patterns/phones.md`, `components/page-header.md`, `components/sheet.md`, `components/list-row.md`. ```text Read https://kwark.space/designSystem/AGENTS.md, https://kwark.space/designSystem/patterns/phones.md and the Page header, Sheet and List row component pages. Make the phone layout of (under 768px wide, and a phone on its side). The desktop layout must not change: put phone rules inside @media (max-width: 767px). One 44px header line: back, a one-word title, at most two labelled actions, and "Menu ▾". The thing the person came for starts by about y = 200: no subtitle, no breadcrumb, no explanatory sentence, no row of chips above it. Rows have no buttons; secondary actions go in the row's ⋯ sheet. One floating control at most; keep --k-fab-slot free at the foot. Tap targets 44px. Describe what you moved where, and check it at 375 and 320. ``` ## Add a component Context: `components.json`, the nearest existing component page, `contributing.md`. ```text Read https://kwark.space/designSystem/components.json and https://kwark.space/designSystem/contributing.md. I need for . First, list the existing components you checked and say why none does the job. If one does, stop and tell me which. If none does, specify the new component the way the Kwark component pages do: what it is, when to use it and when not, anatomy, tokens (only --k-*), every state, the words it uses, accessibility (role, keyboard, accessible name, focus), rules starting with Must, Never or Always, and an AI readiness test. Give the HTML with kw- classes and the CSS using only tokens. Mark it "Ready for Kwark". ``` ## Write a decision record Context: `method/decision-records.md`, `contributing.md`, `foundations/principles.md`. ```text Read https://kwark.space/designSystem/contributing.md (the template) and https://kwark.space/designSystem/foundations/principles.md. Write a decision record for . Use the template exactly, every section. Name a real person and situation in Problem. Give at least two alternatives and why each lost. Name the principle the decision serves. Say what evidence would make us remove it. Status: Draft (rationale to confirm). Do not invent quotes, users, numbers or research; where the source is our conversation, say so. ``` ## Run a readiness test Context: the page under test, nothing else. ```text Read only https://kwark.space/designSystem/.md. Do not use anything you know about Kwark from elsewhere. Answer as you would in real work. Then list which tokens, components and rules from the page you used. ``` Grade the answer against the page's "A reliable answer" list. See [Readiness tests](https://kwark.space/designSystem/agents/readiness.md) for how to grade. ## AI readiness test **Task:** Choose the right prompt from this page for "the Schedule screen looks wrong on my phone", adapt it, and name the files to load. **Give the agent:** This page, AI context files. **Constraint:** Adapt the prompt; do not write a new one from scratch. **A reliable answer:** - Picks the phone layout prompt - Loads AGENTS.md, patterns/phones.md, page-header, sheet and list-row - Keeps the desktop layout unchanged - Asks for checks at 375 and 320 --- # Readiness tests > How to test whether an agent really follows the Kwark system - the readiness test at the end of each page, how to run and grade it in a fresh conversation, what a reliable answer looks like, and every page that has one. Source: https://kwark.space/designSystem/agents/readiness ## Why test An agent that has read a page can still ignore it. It will often produce something that looks right and quietly uses a hex value, an unlabelled icon or an "Are you sure?" the page told it not to. You only find out by asking it to do real work with the page and checking the result against what the page says. Every foundation, pattern, kit and component page ends with an **AI readiness test**: one task, the context to give, a constraint, and the list of things a reliable answer contains. It tests the page as much as the agent. If several agents fail the same test in the same way, the page is unclear, and the page is what gets fixed. ## The shape of a test - **Task.** Real work in Kwark's world: "Restyle a settings panel so it works in the Paper room and in dark mode." - **Give the agent.** The page, and the few other files the task needs. Nothing else. - **Constraint.** The limit that makes the test meaningful: "No new colours. Say which roles you used." - **A reliable answer.** Four to six things that must be true of the answer. Each one is checkable by reading the answer, without judgement calls. ## How to run one 1. **Start a fresh conversation.** No earlier messages, no project memory, no `CLAUDE.md` with Kwark rules in it. You are testing what the page teaches, not what the agent already picked up. 2. **Give it only the listed context.** Paste the markdown twins (switch to **Agent**, then **Copy markdown**) or give the `.md` URLs. Do not add hints. 3. **Paste the task and the constraint**, as written. Use the [readiness prompt](https://kwark.space/designSystem/agents/prompts.md) if you want the agent to also list what it used. 4. **Let it answer once.** Do not correct it mid-answer; a correction is a second test. 5. **Grade** against the reliable-answer list. Run each test in every tool your team uses. The same page can pass in one model and fail in another. ## How to grade Grade each item on the list as met or not met. There is no partial credit and no overall score to chase. | Result | What it means | What to do | |---|---|---| | Every item met | The page is ready for this agent. | Keep the test; run it again when the page changes. | | One item missed | The agent is close, or the page buries that rule. | Read the page as the agent did. If the rule is in a paragraph rather than a **Must** line, promote it. | | Several items missed | The agent did not use the page, or the page is unclear. | Check the agent was given the page. Then rewrite the page, not the test. | | An invented token, component or rule | The most serious failure. | The page must say plainly what to do when something is missing: stop and ask. | **Do:** Count what the answer did: "Used --k-surface and --k-text, no hex, contrast checked in dark, did not assume copper." Four of four met. **Don't:** "Looks good, about 8 out of 10." A feeling is not a grade, and a score hides which rule failed. ## What a reliable answer looks like A reliable answer is specific in the same ways every time: - It uses names from the page exactly: `--k-text-2`, not "the secondary text colour"; `Sheet`, not "a bottom drawer". - It says which tokens, components and rules it used. - It says plainly where the system did not cover something, and asks, instead of inventing. - It covers the states the page lists: empty, loading, error, offline, read-only. - It keeps Kwark's limits without being reminded: no judgement of the writing, nothing a machine writes without a revision mark, no glow. An answer can be well written and still unreliable. Grade what it does, not how confident it sounds. ## Writing a new test - The task is something a real Kwark team would ask for, in Kwark's world (Scene 12, the call sheet, Mira, Act 2). - The constraint closes the easy way out ("No new colours", "Phone first", "Name the components"). - Every item on the reliable list is checkable by reading. "Uses only --k-* roles" is checkable; "feels calm" is not. - Four to six items. More, and nobody runs it. ## Every page with a test Each of these pages ends with its own test. ### Getting started and agents - [About the system](https://kwark.space/designSystem/about.md): What the Kwark Design System is, who it is for, what is inside, how it is versioned and what the status labels on each page mean. - [Designing with the system](https://kwark.space/designSystem/designing.md): How a designer works with the Kwark system - foundations first, then components and patterns, the journey before any build, a decision record for every choice and a review with screenshots. - [Developing with the system](https://kwark.space/designSystem/developing.md): How to use kwark.css and tokens.json in any codebase, which React components exist in the Kwark app and where to import them, the tests that keep the code inside the system, and how to theme with dark mode, writing rooms and a project accent. - [Contributing](https://kwark.space/designSystem/contributing.md): How to propose a change to the Kwark system, write the decision record, get it reviewed, and what every control must meet before it is called done. - [Releases](https://kwark.space/designSystem/releases.md): What is in each version of the Kwark Design System, what changed, what is known to be missing, and what comes next. - [For agents](https://kwark.space/designSystem/agents/index.md): Kwark is written for two readers, people and the agents that build with them. Start here to connect Claude Code, Cursor, Codex or Gemini to the system in three steps. - [AI context files](https://kwark.space/designSystem/agents/ai-context.md): The files an agent can load - llms.txt, llms-full.txt, the markdown twins, AGENTS.md, tokens.json and components.json - what each is for, how to load it, and which one to use for which task. - [Prompt library](https://kwark.space/designSystem/agents/prompts.md): Copy-ready prompts for building with the Kwark system - a screen, a review, UX copy, a phone layout, a new component, a decision record and a readiness test - each with the context files it needs. - [Design-to-code handoff](https://kwark.space/designSystem/agents/handoff.md): How Kwark hands a design to whoever builds it, a person or an agent - a spec that names components and tokens, covers phone and desktop, every state, every word, accessibility and edge cases, with a template to download. - [MCP server](https://kwark.space/designSystem/agents/mcp.md): Install the Kwark design MCP server in Claude Code, Cursor, Codex or Gemini so an agent can search the docs, read any page, look up components and tokens, and audit its own code against the system. - [Skills](https://kwark.space/designSystem/agents/skills.md): Fourteen downloadable agent skills that teach Claude (and any agent that reads SKILL.md files) to build, review, write copy, hand off, record decisions and start a creative app the Kwark way. - [AI-ready roadmap](https://kwark.space/designSystem/agents/roadmap.md): Kwark's own model for a creative-app team adopting the system - six stages, seventeen steps, a "ready enough" line and an AI readiness check for each, statuses instead of scores, and the order the steps depend on. ### Foundations - [Colour](https://kwark.space/designSystem/foundations/color.md): Colour in Kwark is a set of roles. Components ask for the page, the surface or the accent, and the theme, the room or the project decides what that is. - [Typography](https://kwark.space/designSystem/foundations/typography.md): Three faces with three jobs, six sizes, and a screenplay page measured against printed scripts down to the character. What to set, at what size, and what never to shrink. - [Radius](https://kwark.space/designSystem/foundations/radius.md): Four corners, each for one kind of thing, a rule for corners inside corners, and the paper that is never rounded more than paper is. - [Elevation](https://kwark.space/designSystem/foundations/elevation.md): Kwark is flat. Depth is a line and a step in tone; a shadow is only for something that floats above the page, and the layers it floats on are numbered once. - [Spacing](https://kwark.space/designSystem/foundations/spacing.md): Six steps from 4 to 32, two densities (a desk and a thumb), a 16px phone gutter, and the room a phone page keeps free at its foot. - [Layout](https://kwark.space/designSystem/foundations/layout.md): Where things go on a phone, a sideways phone, a tablet, a desk and a television, decided by one shared compact query, with the screenplay page at the centre of every one. - [Motion](https://kwark.space/designSystem/foundations/motion.md): Motion in Kwark answers something a person did, lasts 120 to 320 milliseconds, eases out, and stops when reduced motion is on. Nothing moves on its own. - [Iconography](https://kwark.space/designSystem/foundations/iconography.md): One icon pack, three sizes, one stroke, and a word beside almost every icon. Which glyph each Kwark module uses, which glyphs may stand alone, and what a chevron promises. - [Design principles](https://kwark.space/designSystem/foundations/principles.md): The rules Kwark decides by, each with its reason, what it changes on screen, where it shows in the app and the trade-off it settles. - [Accessibility](https://kwark.space/designSystem/foundations/accessibility.md): WCAG 2.2 AA is the floor. This page gives Kwark's contrast per role, the keyboard map for the screenplay, timeline and boards, focus, screen readers, targets, motion, zoom, media and the checks every change must pass. - [Inclusive design](https://kwark.space/designSystem/foundations/inclusive-design.md): Who Kwark is for, what each of them stands to lose, and how Kwark decides on their behalf: students from 13, cheap phones on slow networks, offline work, many languages, calm for every kind of mind, privacy and cost. - [Writing rooms](https://kwark.space/designSystem/foundations/rooms.md): The screenplay editor's five rooms (Studio, Daylight, Paper, Lamplight, Midnight): what each is made of, how every colour in the editor is worked out from it, the legibility maths, and the rules for building inside one. - [Writing systems](https://kwark.space/designSystem/foundations/writing-systems.md): How Kwark writes a screenplay in more than one language and script: the four language modes, phonetic typing on an English keyboard, fonts per script, right-to-left lines, print and PDF limits, numerals, case and sorting. - [Content](https://kwark.space/designSystem/foundations/content.md): Kwark's voice and tone: calm, plain and film-literate. How Kwark talks about saving and errors, the film words it uses and how, capitalisation, numbers, dates and times for crews, and names and roles. - [UX writing](https://kwark.space/designSystem/foundations/ux-writing.md): The micro-copy handbook. How Kwark words buttons, labels, errors, empty states, confirmations, toasts, notifications, first runs, settings and machine suggestions, with before and after tables from real Kwark strings and a word list. - [AI and authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md): Kwark's stance on machines and the writer's work. What a machine may and may not do in Kwark, how anything it proposes is marked, sourced, consented to and undone, what happens to the work's privacy, and why Kwark chose the margin mark over the industry's sparkles and glows. - [Data visualisation](https://kwark.space/designSystem/foundations/data-visualization.md): The charts Kwark draws (the timeline, the story spine, the stripboard, the calendar, Dailies, the budget's top sheet), the colours they use and in what order, labels over legends, accessible alternatives, and the one chart Kwark never draws: a score for the writing. ### Patterns - [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. - [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. - [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. - [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. - [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. - [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. - [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. - [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. - [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. - [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. - [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. - [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. - [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. ### Creative app kits - [Screenwriting](https://kwark.space/designSystem/kits/screenwriting.md): Build a writing surface whose page on screen is the printed page, with the elements, revisions, outline and timeline a working screenwriter expects, and nothing that judges the work. - [Editing](https://kwark.space/designSystem/kits/editing.md): Build a picture editor or review tool on Kwark: a bin that knows the script, source and program viewers, a multitrack timeline with one coral playhead, timecode written correctly, and the keyboard editors already use. - [Storyboard and shots](https://kwark.space/designSystem/kits/storyboard-and-shots.md): Build shot planning the way a director and DP think about it: shots named by scene and letter, framing in industry terms, coverage lined on the script, boards at the film's aspect ratio, setups for the crew, and an animatic. - [Scheduling and call sheets](https://kwark.space/designSystem/kits/scheduling-and-call-sheets.md): Build the first AD's tools: a stripboard in pages and eighths with the four paper colours, shooting days, day out of days, and call sheets issued as numbered, frozen revisions that print, save as PDF and download as CSV. - [Sound](https://kwark.space/designSystem/kits/sound.md): Build a sound session or dubbing tool on Kwark: tracks named by character, waveforms with fades and clip gain, a mixer in signal order, loudness against the target the project chose, and ADR cues made from the screenplay. - [Colour grading](https://kwark.space/designSystem/kits/colour-grading.md): Build a grading or dailies colour tool on Kwark: a neutral viewer with before and after, scopes that measure, primaries with numbers, a node graph that shows order, clips with versions, and looks named by their colour spaces. - [Production office](https://kwark.space/designSystem/kits/production-office.md): Build the producer's and line producer's tools on Kwark: a marked-up breakdown that writes its own sheets, cast and locations that feed the budget, paperwork that remembers when it was checked, and sharing by film role. - [Any creative app](https://kwark.space/designSystem/kits/any-creative-app.md): Carry Kwark's approach into another craft, such as music, animation, theatre, comics, games or podcasts, without importing film-specific assumptions: find the craft's own paper, its own units and its own conventions, then build them as one act. ### Components Every component has its test in the **For agents** tab of its page. The full list is in the [component catalogue](https://kwark.space/designSystem/components.md) and in `components.json`; each entry's `docs` URL leads to the page with the test. - [Component catalogue](https://kwark.space/designSystem/components.md): Every part Kwark is built from, drawn from the running app, with where each variant lives, its exact geometry, and the rules an agent must follow to use it. ## AI readiness test **Task:** Run the readiness test from the Colour page against two agents and report the result. **Give the agent:** This page, the Colour page's markdown twin. **Constraint:** Fresh conversations, only the listed context, one answer each. **A reliable answer:** - Starts each agent in a fresh conversation - Gives only the Colour page and the files its test names - Grades each reliable item as met or not met with no score - Names which rule failed when an item is missed - Proposes a page change rather than a test change when both agents miss the same item --- # AI-ready roadmap > Kwark's own model for a creative-app team adopting the system - six stages, seventeen steps, a "ready enough" line and an AI readiness check for each, statuses instead of scores, and the order the steps depend on. Source: https://kwark.space/designSystem/agents/roadmap ## What this is for A team adopting the Kwark system for a creative app (a script tool, an editor, a storyboard, a scheduler, a sound or grading tool, a production office) has to do two things at once: make the product consistent, and make it something an agent can build on without inventing. This roadmap is the order Kwark does both in. It is written for creative tools on purpose. A general product can get away with tokens and a component library. A creative tool cannot, because the hard parts are elsewhere: the person's work on the page, a timeline with a playhead, media that is large and offline, a writer's chosen room, and a printed artefact the industry has used for decades. An agent that knows your buttons but not your script model will still break the script. **[Download the roadmap context file (markdown)](https://kwark.space/designSystem/agents/roadmap-context.md)**. Put it in your repository as `docs/roadmap.md`, keep the statuses current, and tell your agents to read it before they start work. It lets an agent say "saving is not ready enough yet, so I will not build the export" instead of building on sand. ## How the model works ### Stages and steps Six stages, seventeen steps. A stage is a kind of readiness; a step is one piece of work with a clear end. Stages are not phases of a project plan: you will work in several at once. What matters is the dependencies between steps, shown below. ### Ready enough Each step has a **ready enough** line: the point where the step is good enough for the steps that depend on it, and for an agent to use. It is not "finished". A step can be ready enough and still improving. The line exists because creative tools are never done, and teams that wait for done never start the next step. It also stops the opposite: building the export on a document model that still changes every week. ### AI readiness check Each step has a check: a task you give an agent in a fresh conversation, with only your published context, that it can do correctly only if the step is ready enough. If the agent fails, the step is not ready, whatever the team thinks. The checks use the same method as the [readiness tests](https://kwark.space/designSystem/agents/readiness.md) on every page. ### Statuses, not scores | Status | Meaning | |---|---| | **Not started** | Nobody owns it yet. | | **Working** | Someone owns it and it is below the ready-enough line. | | **Ready enough** | It meets the line and its AI readiness check passes. Steps that need it can start. | | **Revisit** | It was ready enough, and something it depends on changed. Run its check again. | There is no maturity level and no percentage. A score hides which step is the problem, invites a team to raise the number rather than fix the work, and says nothing an agent can act on. A status per step does. (Kwark does not score people's scripts either; it would be odd to score a team.) ## The dependency order | Step | Needs before it can be ready enough | |---|---| | 1 People and artefacts | nothing | | 2 Principles you adopt | 1 | | 3 Screens and parts inventory | 1 | | 4 Tokens | 3 | | 5 Themes, rooms and accent | 4 | | 6 Type and scripts | 4 | | 7 The work model | 1 | | 8 Saving, sync and offline | 7 | | 9 Undo, trash and revisions | 7, 8 | | 10 Shared parts and shells | 3, 4 | | 11 Creative-tool parts | 7, 10 | | 12 The printed artefact | 6, 7 | | 13 Your AGENTS.md and context | 2, 4, 10 | | 14 Authorship rules for machines | 2, 7, 9 | | 15 Readiness tests and review | 13 | | 16 Enforcement in the build | 4, 10 | | 17 Versioning and release | 13, 16 | Two chains matter most. **The work chain** (1, 7, 8, 9, then 11, 12, 14) decides whether people can trust the product with their work. **The system chain** (3, 4, 10, then 13, 16) decides whether the product stays consistent. They can run side by side, and they meet at step 13, where an agent is given both. > The most common mistake is to start at step 10, a component library, because it is the visible part. A library built before the inventory (3) and the tokens (4) encodes today's inconsistencies. A library built before the work model (7) gets a timeline component that cannot hold the real data. ## Stage 1 · Ground: know the work ### Step 1 · Name the people and their artefacts Write who makes what in your product, in what situation, and the artefact the industry already uses for it: the screenplay page, the stripboard, the call sheet, the edit decision list, the cue sheet, the shot list, the colour report. The digital version will be that artefact, not a table beside it. - **Ready enough:** every main screen maps to a named person and a named artefact, and the team agrees on the words. - **AI readiness check:** give an agent only this document and ask it to name the screen a 2nd AD uses at 6am on a shoot day, and what that screen must print. It answers with your artefact and your words, not generic "dashboard" language. ### Step 2 · Record the principles you adopt Kwark's principles (the writer first, private and safe, no judgement of the work, nothing compulsory, structure not teaching, paper and digital as one act) are opinions. Decide which you keep, which you change, and write each as a decision record with its reason. See [Principles](https://kwark.space/designSystem/foundations/principles.md) and [Decision records](https://kwark.space/designSystem/method/decision-records.md). - **Ready enough:** each principle you keep has a record with a test ("Does this measure the work, or evaluate it?"), and the ones you drop are written down too. - **AI readiness check:** ask an agent, with only your records, to design a "progress" feature for writers. It refuses or reshapes anything your principles rule out (streaks, scores, public counts) and cites the record. ### Step 3 · Inventory the screens and parts List every screen, and every part on it: each button style, each dialog, each badge, dot and count, and what it means. Kwark keeps two lists: a map of components and the screens that use them, and an element register that gives every dot and badge a meaning and a reason. Anything with no reason is a candidate for removal. - **Ready enough:** you can say for every visible element which component it should be, and every dot, badge and count has a written meaning. - **AI readiness check:** give an agent a screenshot of one screen and the inventory. It names each part's component and flags the elements not in the register. ## Stage 2 · Foundations: tokens, rooms and type ### Step 4 · Adopt the tokens Replace values with roles: `--k-*` tokens from `kwark.css`, or your own names mapped onto them through `tokens.json`. Map every colour, size, radius, space and duration you found in step 3 to a role. Two values doing the same job become one. See [Developing](https://kwark.space/designSystem/developing.md). - **Ready enough:** new code uses only tokens, and the old values are mapped (even if not yet replaced everywhere). - **AI readiness check:** ask an agent to restyle one panel with only `tokens.json` and `AGENTS.md`. It uses no hex, rgb or px font sizes, and names each role it used. ### Step 5 · Themes, rooms and the project accent Dark and light, the rooms people choose for their working surface, and a project's own colour. In a creative tool the working surface is the person's space: a writer in Midnight at 2am, a colourist in a neutral room for accurate judgement. Decide which surfaces follow a room and which never do (a grading viewer must stay neutral). See [Writing rooms](https://kwark.space/designSystem/foundations/rooms.md). - **Ready enough:** every token has a light and a dark value, each room passes contrast for text and controls, and a pale and a dark project accent both read. - **AI readiness check:** ask an agent to add a "Scene notes" panel inside the working surface. It uses roles that follow the room, sets `--k-on-accent` with any accent, and checks contrast in every room without being told to. ### Step 6 · Type and scripts The UI type scale, and the type of the work itself: screenplay geometry (Courier Prime at 12pt, the industry's page), timecode, music notation, whatever your artefact uses. Then every script your people write in. Kwark writers type in Hindi, Tamil and other Indian scripts, and the PDF route for those scripts is different from the Latin one (see [Writing systems](https://kwark.space/designSystem/foundations/writing-systems.md)). - **Ready enough:** the work's type matches the industry's page measurements, and a line in each supported script displays, edits, wraps and prints correctly. - **AI readiness check:** ask an agent to add a bilingual dialogue line (English and Hindi) to a script view. It keeps the work's font role, does not shrink the Indian script below the scale, and says how the line will print. ## Stage 3 · The work is safe: data, saving and offline ### Step 7 · The work model Write down the shape of the person's work so a person and an agent read it the same way: a script as scenes and elements (heading, action, character, dialogue, parenthetical, transition); a timeline as tracks, clips, in and out points in timecode; a board as panels tied to shots; a schedule as strips tied to scenes, cast and locations. Say which fields are the person's words and which are derived. Say how big it can get (a feature film, a 200-strip schedule, an hour of media). - **Ready enough:** a written model with field names, types, limits and which fields a machine may never write; existing data loads into it, including old records with missing fields. - **AI readiness check:** give an agent the model and ask it to add a "runtime per scene" display. It reads only derived fields, writes nothing into the person's text, and handles a scene with no dialogue. ### Step 8 · Saving, sync and offline The person's biggest fear is losing work. Autosave, one calm word for the state, work kept on the device when the network goes, and a clear choice when two sessions disagree. Media is large: say what is on this device and what is not. See [Saving and sync](https://kwark.space/designSystem/patterns/saving-and-sync.md) and Decision 0013. - **Ready enough:** every state has a fixed word, no message says "failed", offline edits survive a reload, and a conflict never overwrites either copy without the person choosing. - **AI readiness check:** ask an agent to add an import for a storyboard image set. Its design says what the person sees when the files reach the device but not the cloud, in your words, and what happens if the import stops halfway. ### Step 9 · Undo, trash and revisions Undo instead of "Are you sure?". A trash that can be restored. Versions people can name and return to. Where the industry numbers revisions (a revised call sheet, coloured script pages), the product numbers them the same way. See [Destructive actions](https://kwark.space/designSystem/patterns/destructive-actions.md). - **Ready enough:** every destructive action can be undone or restored, and issued artefacts keep numbered revisions that do not change once issued. - **AI readiness check:** ask an agent to add "Delete Act 2". It offers Undo, names the object and its contents in any confirmation, and keeps the scenes recoverable. ## Stage 4 · Parts and shells ### Step 10 · Shared parts and the two shells The shared components, used everywhere, and the two shells: desktop with File, Edit, View, Tools and Help menus and real shortcuts; phone with one header line, content first and one floating control. See [Components](https://kwark.space/designSystem/components.md), [Phones](https://kwark.space/designSystem/patterns/phones.md) and [Menus and shortcuts](https://kwark.space/designSystem/patterns/menus-and-shortcuts.md). - **Ready enough:** every new screen is built from shared parts, every control has a word or a named icon, and the phone layout of each main screen starts its content by about y = 200. - **AI readiness check:** ask an agent to build a settings screen for desktop and phone. It uses only listed components, puts menus in a bottom sheet on the phone, and labels every control. ### Step 11 · Creative-tool parts The parts only creative tools need: the page view, the timeline and playhead, scrubbing, index cards, boards, the stripboard, waveforms, the revision mark for machine suggestions. Each is built on the work model (step 7), not on a mock-up. See the [Creative app kits](https://kwark.space/designSystem/kits.md). - **Ready enough:** each part handles the real data at its real size (a feature-length timeline, a long scene, an empty board) with keyboard control and a phone form. - **AI readiness check:** ask an agent to add markers to the timeline. It uses the timeline component and the model's timecode fields, gives each marker a name for screen readers, and keeps the phone strip readable. ## Stage 5 · Paper and print ### Step 12 · The printed artefact Print or export the artefact at the industry's geometry from the start: the screenplay page, the call sheet a crew reads on paper, the shot list on a clipboard. Paper and digital are made as one act; the printout is not an afterthought. See [Print and export](https://kwark.space/designSystem/patterns/print-and-export.md). - **Ready enough:** the printout matches the industry page (margins, page breaks, numbering), every supported script prints correctly, and a printed revision shows its number. - **AI readiness check:** ask an agent to add a field to the call sheet. It adds it to the printed sheet in the same change and says where it falls on the page. ## Stage 6 · Agents in the loop ### Step 13 · Your AGENTS.md and context Write your product's own `AGENTS.md`: Kwark's rules plus yours (your work model, your principles, your artefacts). Publish markdown twins for your docs, and install the [MCP server](https://kwark.space/designSystem/agents/mcp.md) and [skills](https://kwark.space/designSystem/agents/skills.md). See [AI context files](https://kwark.space/designSystem/agents/ai-context.md). - **Ready enough:** a new agent, given only your published context, builds a small screen that passes review without a correction. - **AI readiness check:** the check is the ready-enough line: one fresh conversation, one small screen, graded against your rules. ### Step 14 · Authorship rules for machines If any part of the product proposes words, frames, cuts or schedules, decide how it is marked, accepted and refused. In Kwark a machine suggests and a person writes: suggestions carry a revision mark until accepted, are never saved into the work on their own, and never score or judge it. See [AI and authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md) and Decision 0002. - **Ready enough:** every machine proposal is visibly marked, needs a person's action to enter the work, can be refused, and nothing anywhere rates the person's work. - **AI readiness check:** ask an agent to add "suggest a scene heading". It shows the suggestion with a revision mark, writes nothing until accepted, and offers no quality judgement. ### Step 15 · Readiness tests and review Add a readiness test to every page you publish, and run the review ladder on every change: a UI reviewer and a UX reviewer who did not build it, review-only, before anything is called done. See [Readiness tests](https://kwark.space/designSystem/agents/readiness.md) and [Contributing](https://kwark.space/designSystem/contributing.md). - **Ready enough:** every page has a test, the tests are run in each agent tool the team uses, and a failed test leads to a page change. - **AI readiness check:** run three tests from different pages in a fresh conversation. All reliable items are met, or the failing page has been rewritten. ### Step 16 · Enforcement in the build Tests that stop drift: a scan that counts colour literals, px font sizes, font names and icon sizes per file and fails when a file gets worse. Kwark's version is described on [Developing](https://kwark.space/designSystem/developing.md). - **Ready enough:** the suite fails on any new violation, and the baseline only goes down. - **AI readiness check:** ask an agent to make a change that would be easier with a hex value. It uses a token, and if it does not, the test fails before review. ### Step 17 · Versioning and release One version number for the system and its files, release notes that name every changed token and component, and agents told which version they are reading. See [Releases](https://kwark.space/designSystem/releases.md). - **Ready enough:** each release has notes, token names do not change inside a major version, and your context files carry the version. - **AI readiness check:** ask an agent what changed between your last two versions and what it must update. It answers from the release notes only. ## Kwark against its own roadmap Kwark is on this roadmap too. Where it stands at v4.0, plainly: | Step | Status | Why | |---|---|---| | 1 People and artefacts | Ready enough | Writers and crew roles, and the artefacts (script, breakdown, stripboard, call sheet, budget) are named in the decision records. | | 3 Screens and parts inventory | Ready enough | A component map and an element register exist, written from the code. | | 4 Tokens | Working | Tokens are in one file; older names still work alongside them while code moves over. | | 5 Themes, rooms and accent | Working | Five writing rooms and the project accent ship; the light theme is unfinished, so the app opens in dark. | | 6 Type and scripts | Working | Indian scripts can be typed and print through the browser; the built-in PDF export is Latin only. | | 8 Saving, sync and offline | Ready enough | Fixed save words and calm sync copy (Decision 0013). | | 12 The printed artefact | Working | Screenplay and call sheet print; some page sizes are still being measured against industry PDFs. | | 13 AGENTS.md and context | Ready enough | This site, its twins, the MCP server and the skills. | | 16 Enforcement in the build | Working | Checks in the build fail any change that adds a raw colour, font, size or a stray breadcrumb. | Steps not listed have not been assessed for this page. ## AI readiness test **Task:** A team building a sound-mixing app asks where to start adopting the Kwark system and what an agent can safely build first. **Give the agent:** This page and the roadmap context file. **Constraint:** Use the steps and statuses here. No maturity levels or scores. **A reliable answer:** - Starts with step 1 and the work model (7), not a component library - Names the sound industry's artefact (a cue sheet or mix notes) in step 1 - Gives the ready-enough line and the AI readiness check for the first steps - Says an agent should not build export or machine suggestions until the steps they depend on are ready enough - Uses the four statuses only --- # Skills > Fourteen downloadable agent skills that teach Claude (and any agent that reads SKILL.md files) to build, review, write copy, hand off, record decisions and start a creative app the Kwark way. Source: https://kwark.space/designSystem/agents/skills ## What a skill is A skill is a folder with a `SKILL.md` file: a short name, a description of when to use it, and the instructions. Claude Code reads the description of every installed skill and loads the instructions only when a task matches, so a skill costs almost nothing until it is needed. Other agents can be given a `SKILL.md` as a plain prompt. Each Kwark skill is small and points to the hosted pages instead of copying them, so it stays current when the system changes. ## The skills | Skill | Use it to | Loads | |---|---|---| | [`kwark-ui`](https://kwark.space/designSystem/skills/kwark-ui/SKILL.md) | Build or change a screen, panel, dialog, menu or component with the system. | AGENTS.md, the component and pattern pages it uses | | [`kwark-ux-review`](https://kwark.space/designSystem/skills/kwark-ux-review/SKILL.md) | Review a screen, screenshot or diff as a review-only supervisor, in Kwark's order: the person, their work, the system, states, accessibility, copy, look. | AGENTS.md, Principles, Review and quality | | [`kwark-ux-copy`](https://kwark.space/designSystem/skills/kwark-ux-copy/SKILL.md) | Write buttons, errors, save states, empty states, confirmations and toasts in Kwark's voice. | UX writing, Content, Errors, Saving and sync, Empty states | | [`kwark-handoff`](https://kwark.space/designSystem/skills/kwark-handoff/SKILL.md) | Write a design-to-code spec from a design description. Comes with [`template.md`](https://kwark.space/designSystem/skills/kwark-handoff/template.md). | Handoff, AGENTS.md, components.json, Phones | | [`kwark-decision-record`](https://kwark.space/designSystem/skills/kwark-decision-record/SKILL.md) | Write a numbered decision record with Kwark's template. | Decision records, Contributing, Principles | | [`kwark-creative-app`](https://kwark.space/designSystem/skills/kwark-creative-app/SKILL.md) | Start a new creative or filmmaking app on the system, in the right order. | llms.txt, AGENTS.md, Developing, Roadmap, the nearest kit | ## Product workflows These eight skills package the product method for a team that has the public system and its own project evidence. | Skill | Use it for | |---|---| | [kwark-frame-problem](https://kwark.space/designSystem/skills/kwark-frame-problem/SKILL.md) | Identify the person, artefact, blockage and evidence before choosing a feature. | | [kwark-map-opportunities](https://kwark.space/designSystem/skills/kwark-map-opportunities/SKILL.md) | Connect an outcome to opportunities, approaches and the next test. | | [kwark-test-assumptions](https://kwark.space/designSystem/skills/kwark-test-assumptions/SKILL.md) | Test the assumption with the greatest consequence and least evidence. | | [kwark-prioritise](https://kwark.space/designSystem/skills/kwark-prioritise/SKILL.md) | Choose a release slice using effect on the work, dependencies and verification cost. | | [kwark-write-spec](https://kwark.space/designSystem/skills/kwark-write-spec/SKILL.md) | Specify records, states, permissions, recovery and acceptance criteria. | | [kwark-synthesise-research](https://kwark.space/designSystem/skills/kwark-synthesise-research/SKILL.md) | Turn supplied observations into findings with traceable sources. | | [kwark-measure-outcome](https://kwark.space/designSystem/skills/kwark-measure-outcome/SKILL.md) | Measure task completion and safety while keeping writing measures private. | | [kwark-check-release](https://kwark.space/designSystem/skills/kwark-check-release/SKILL.md) | Assess the actual build against the agreed journey and evidence. | To install a product workflow, replace the skill name below with the one you need. ```bash mkdir -p ~/.claude/skills/kwark-frame-problem curl -fsSL https://kwark.space/designSystem/skills/kwark-frame-problem/SKILL.md -o ~/.claude/skills/kwark-frame-problem/SKILL.md ``` ## Install ### For you, in every project ```bash for s in kwark-ui kwark-ux-review kwark-ux-copy kwark-handoff kwark-decision-record kwark-creative-app; do mkdir -p ~/.claude/skills/$s curl -fsSL https://kwark.space/designSystem/skills/$s/SKILL.md -o ~/.claude/skills/$s/SKILL.md done curl -fsSL https://kwark.space/designSystem/skills/kwark-handoff/template.md -o ~/.claude/skills/kwark-handoff/template.md ``` ### For a team, in one repository The same loop with `.claude/skills/` instead of `~/.claude/skills/`, run from the repository root. Commit the folder so everyone who opens the project gets the same skills. ```bash for s in kwark-ui kwark-ux-review kwark-ux-copy kwark-handoff kwark-decision-record kwark-creative-app; do mkdir -p .claude/skills/$s curl -fsSL https://kwark.space/designSystem/skills/$s/SKILL.md -o .claude/skills/$s/SKILL.md done curl -fsSL https://kwark.space/designSystem/skills/kwark-handoff/template.md -o .claude/skills/kwark-handoff/template.md ``` Install only the ones you need; each works alone. Restart Claude Code, or start a new session, to pick them up. Ask "which skills do you have?" to check. ### In other agents - **Cursor:** save a `SKILL.md` as a rule in `.cursor/rules/` (rename it `.mdc`), and set it to apply when relevant. - **Codex:** add the skill's instructions as a section of the repository's `AGENTS.md`, or paste it at the start of the task. - **Gemini:** add it to `GEMINI.md`, or paste it at the start of the conversation. ## Using them Name the skill when you want a specific one, or describe the task and let the agent choose: - "Use kwark-ui to add the Rename scene dialog." - "Review this diff with kwark-ux-review. Don't change anything." - "kwark-ux-copy: the import reached this device but not the cloud. What does the toast say?" - "Write the handoff for the call sheet's Issue action with kwark-handoff." - "Record why phones get one floating control, using kwark-decision-record." - "We're starting a sound-mixing app. Set it up with kwark-creative-app." The skills work best with the [MCP server](https://kwark.space/designSystem/agents/mcp.md) installed: they tell the agent to use `get_component`, `get_tokens` and `audit_code` when they are available. > **For agents:** When a Kwark skill is active, follow its Load first list before writing anything, and its Rules over any default you would otherwise use. If a page the skill names cannot be fetched, say so and continue with AGENTS.md; do not reconstruct the page from memory. ## AI readiness test **Task:** Install the Kwark review and copy skills for a team repository and show how a reviewer would use them on a pull request. **Give the agent:** This page. **Constraint:** Project-level install only. Use the URLs on this page. **A reliable answer:** - Installs into .claude/skills in the repository and commits the folder - Fetches SKILL.md for kwark-ux-review and kwark-ux-copy - Names the skill in the request - Keeps the review read-only - Mentions the MCP server as optional, not required --- # For agents > Kwark is written for two readers, people and the agents that build with them. Start here to connect Claude Code, Cursor, Codex or Gemini to the system in three steps. Source: https://kwark.space/designSystem/agents ## Why two readers Most of the interface code written today passes through an agent. An agent that has never seen your system fills the gaps with the most common answer it knows: a blue button, a grey card, a modal that says "Are you sure?". That is how products drift into looking like every other product. So every page here is written once and published twice: - **For people**: the page you are reading, with live components, Light and Dark, do and don't pairs. - **For agents**: the same source as plain markdown, plus files an agent can load whole: `AGENTS.md` for the rules, `tokens.json` for values, `components.json` for parts, `llms.txt` as the map. The rules are written so an agent can follow them without interpretation. They start with **Must**, **Never** or **Always**, they name tokens and components exactly, and each page ends with a readiness test you can use to check that an agent has understood it. ## The Person and Agent switch At the top of every page, **Person** and **Agent** switch the view. Agent shows the page exactly as an agent reads it: the markdown twin, with **Copy markdown** to paste into a chat and **Open .md** for the file. Nothing is hidden from either reader: the agent view is not a summary, it is the same page. You can also add `.md` to any URL: ```text https://kwark.space/designSystem/components/breadcrumb for people https://kwark.space/designSystem/components/breadcrumb.md for agents ``` ## Quick start Three steps, whichever tool you use. ### Claude Code 1. Add the rules to the project. In `CLAUDE.md`, add one line: `Follow https://kwark.space/designSystem/AGENTS.md for all UI. Load component pages from https://kwark.space/designSystem/components/.md before using a part.` 2. Install the MCP server so Claude can search the docs, read tokens and audit its own code: `claude mcp add kwark-design -- node /absolute/path/to/kwark-design-mcp.mjs`. See [MCP server](https://kwark.space/designSystem/agents/mcp.md). 3. Install the skills into `~/.claude/skills/` or the project's `.claude/skills/`. See [Skills](https://kwark.space/designSystem/agents/skills.md). Then ask: "Use kwark-ui to build the Scene notes panel." ### Cursor 1. Add a project rule: create `.cursor/rules/kwark.mdc` with the contents of [AGENTS.md](https://kwark.space/designSystem/AGENTS.md), or a single line pointing to it. 2. Add the MCP server in `.cursor/mcp.json` (the snippet is on [MCP server](https://kwark.space/designSystem/agents/mcp.md)). 3. Add `https://kwark.space/designSystem/llms.txt` as a documentation source and reference it with `@Docs`, or paste the `.md` URLs of the pages you need into the chat, then ask for the screen. ### Codex 1. Put the rules in the repository's `AGENTS.md`. Codex reads it automatically. Copy the file from `https://kwark.space/designSystem/AGENTS.md`, or add a section that links to it. 2. Add the MCP server in `~/.codex/config.toml` (snippet on [MCP server](https://kwark.space/designSystem/agents/mcp.md)). 3. Ask for one screen at a time and name the pages to read: "Read patterns/saving-and-sync.md and components/toast.md, then add the import toast." ### Gemini 1. Put the rules in `GEMINI.md` at the root of the project, or paste `AGENTS.md` at the start of the conversation. 2. With Gemini CLI, add the MCP server under `mcpServers` in `~/.gemini/settings.json` (snippet on [MCP server](https://kwark.space/designSystem/agents/mcp.md)). 3. Give it `llms.txt` to find pages, and load only the pages the task needs. > **For agents:** If you are an agent reading this: read AGENTS.md before writing any UI, load the component and pattern pages for the parts you use, use only --k-* tokens and the components listed in components.json, and say plainly when the system does not cover something. Never invent a token, a component or a rule. ## What is here - [AI context files](https://kwark.space/designSystem/agents/ai-context.md): The files an agent can load - llms.txt, llms-full.txt, the markdown twins, AGENTS.md, tokens.json and components.json - what each is for, how to load it, and which one to use for which task. - [Prompt library](https://kwark.space/designSystem/agents/prompts.md): Copy-ready prompts for building with the Kwark system - a screen, a review, UX copy, a phone layout, a new component, a decision record and a readiness test - each with the context files it needs. - [Design-to-code handoff](https://kwark.space/designSystem/agents/handoff.md): How Kwark hands a design to whoever builds it, a person or an agent - a spec that names components and tokens, covers phone and desktop, every state, every word, accessibility and edge cases, with a template to download. - [MCP server](https://kwark.space/designSystem/agents/mcp.md): Install the Kwark design MCP server in Claude Code, Cursor, Codex or Gemini so an agent can search the docs, read any page, look up components and tokens, and audit its own code against the system. - [Skills](https://kwark.space/designSystem/agents/skills.md): Fourteen downloadable agent skills that teach Claude (and any agent that reads SKILL.md files) to build, review, write copy, hand off, record decisions and start a creative app the Kwark way. - [Readiness tests](https://kwark.space/designSystem/agents/readiness.md): How to test whether an agent really follows the Kwark system - the readiness test at the end of each page, how to run and grade it in a fresh conversation, what a reliable answer looks like, and every page that has one. - [AI-ready roadmap](https://kwark.space/designSystem/agents/roadmap.md): Kwark's own model for a creative-app team adopting the system - six stages, seventeen steps, a "ready enough" line and an AI readiness check for each, statuses instead of scores, and the order the steps depend on. ## AI readiness test **Task:** Set up a new repository so that Claude Code follows the Kwark system for all UI work. **Give the agent:** This page, MCP server, Skills. **Constraint:** Only files and commands named on these pages. **A reliable answer:** - Adds a CLAUDE.md line pointing to AGENTS.md - Installs the MCP server with an absolute path - Installs at least kwark-ui and kwark-ux-review - Explains how to load a single page's .md twin - Does not paste llms-full.txt into every conversation --- # Component catalogue > Every part Kwark is built from, drawn from the running app, with where each variant lives, its exact geometry, and the rules an agent must follow to use it. Source: https://kwark.space/designSystem/components ## How to read this catalogue Each specimen is the Kwark component as the app draws it, measured from the running app or translated from its source in `components/ui`, `pages/**` and `styles/tokens.css`. Where Kwark draws the same thing in more than one way, the page shows each look as a variant and says where it lives: the [Button](https://kwark.space/designSystem/components/button.md) has the shared button, the story-surface button used in modules and dialogs, and the light resume control on Project home. Every component page has five tabs: **Usage** (when, when not, variants, writing), **Style** (anatomy with measurements, and the tokens it uses), **Code** (the React import and props where the app has one, and framework-free HTML with `kwark.css`), **Accessibility** (keyboard and ARIA) and **For agents** (rules and a readiness test). ## Status | Label | Means | |---|---| | **In the app** | Kwark has this component. The Code tab names the file. | | **Ready for Kwark** | Kwark does not have it yet. It is specified in Kwark’s tokens, corners, type and voice so it can be built without a new look. The page says what Kwark does today instead. | | **New** | A design-system proposal the app is adopting, such as the [revision mark](https://kwark.space/designSystem/components/revision-mark.md). | Some pages also carry a section called *Moving older code over*. It names where the app still draws an older style (upper-case button labels, the legacy badge, the old confirm dialog) and which look replaces it when that file is next touched (docs/design-system.md, section 7). ## Start with what Kwark is made of - [Button](https://kwark.space/designSystem/components/button.md): Starts an action. Kwark draws it in three places with three weights: the shared button, the story-surface button in modules and dialogs, and the light resume control on Project home. - [Breadcrumb](https://kwark.space/designSystem/components/breadcrumb.md): Keep the project, phase and active module visible as a filmmaker moves between rooms. - [Menu](https://kwark.space/designSystem/components/menu.md): A short list of commands that opens from a button or a right-click. Desktop-grade, with shortcuts. - [Dialog](https://kwark.space/designSystem/components/dialog.md): Stops the work to ask one question or collect a small form. Use rarely. - [Toast](https://kwark.space/designSystem/components/toast.md): Give a short receipt for an action, with enough time to dismiss it or undo it. - [Floating dial](https://kwark.space/designSystem/components/floating-dial.md): On phones, one 48px button at the foot of the screen that fans out Comments, Quick note and Account. ## The film’s own artefacts - [Project cover](https://kwark.space/designSystem/components/project-cover.md): The poster a project wears at 2:3, with its one ⋯ cover menu inside the poster, and a designed placeholder when there is no cover. - [Index card](https://kwark.space/designSystem/components/index-card.md): A beat or scene on card stock: a title above a red rule, notes on blue lines, and where it lands in the script. - [Stripboard strip](https://kwark.space/designSystem/components/stripboard-strip.md): A scene as a strip of coloured paper: white, yellow, blue or green for interior or exterior, day or night. Days hold strips. - [Call sheet](https://kwark.space/designSystem/components/call-sheet.md): The day's sheet on paper: production, call time, scenes, cast, locations and safety, issued as numbered, frozen revisions. ## Machines and authorship Kwark never judges the script (Decision 0002). These parts let a machine find, move, carry or convert the writer’s own material, and nothing more. Read [AI and authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md) first. - [Revision mark](https://kwark.space/designSystem/components/revision-mark.md): 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. - [Suggestion panel](https://kwark.space/designSystem/components/suggestion-panel.md): Proposals drawn from the writer’s own material, kept beside the page and not in it: a heading from an outline beat, a prop the script mentions. - [AI result review](https://kwark.space/designSystem/components/ai-review.md): A batch of proposals drawn from the writer’s own material, each shown in place with its source and its own Use or Not needed. - [AI consent prompt](https://kwark.space/designSystem/components/ai-consent.md): Before anything a person writes leaves the device: what is sent, to whom, what is kept, and a choice that starts off. ## All components by job Components are grouped by what they do: Actions, Inputs, Selection, Navigation, Feedback, Overlays, Layout, Data display, Data visualisation, Media, Creative tools, AI and authorship, and Collaboration. ### Actions - [Button](https://kwark.space/designSystem/components/button.md) - [Button group](https://kwark.space/designSystem/components/button-group.md) - [Copy field](https://kwark.space/designSystem/components/copy-field.md) - [Floating action button](https://kwark.space/designSystem/components/floating-action.md) - [Floating dial](https://kwark.space/designSystem/components/floating-dial.md) - [Icon button](https://kwark.space/designSystem/components/icon-button.md) - [Split button](https://kwark.space/designSystem/components/split-button.md) - [Text button](https://kwark.space/designSystem/components/text-button.md) ### Inputs - [Date picker](https://kwark.space/designSystem/components/date-picker.md) - [File uploader](https://kwark.space/designSystem/components/file-upload.md) - [Number stepper](https://kwark.space/designSystem/components/number-stepper.md) - [Search field](https://kwark.space/designSystem/components/search-field.md) - [Slider](https://kwark.space/designSystem/components/slider.md) - [Text input](https://kwark.space/designSystem/components/text-input.md) - [Textarea](https://kwark.space/designSystem/components/textarea.md) - [Time picker](https://kwark.space/designSystem/components/time-picker.md) ### Selection - [Checkbox and radio](https://kwark.space/designSystem/components/checkbox-and-radio.md) - [Chip](https://kwark.space/designSystem/components/chip.md) - [Colour picker](https://kwark.space/designSystem/components/colour-picker.md) - [Combobox](https://kwark.space/designSystem/components/combobox.md) - [Icon toggle](https://kwark.space/designSystem/components/icon-toggle.md) - [Multiselect](https://kwark.space/designSystem/components/multiselect.md) - [Removable tag](https://kwark.space/designSystem/components/removable-tag.md) - [Segmented control](https://kwark.space/designSystem/components/segmented-control.md) - [Select](https://kwark.space/designSystem/components/select.md) - [Switch](https://kwark.space/designSystem/components/switch.md) ### Navigation - [Account menu](https://kwark.space/designSystem/components/account-menu.md) - [Bottom navigation](https://kwark.space/designSystem/components/bottom-navigation.md) - [Breadcrumb](https://kwark.space/designSystem/components/breadcrumb.md) - [Command palette](https://kwark.space/designSystem/components/command-palette.md) - [Link](https://kwark.space/designSystem/components/text-link.md) - [Page header](https://kwark.space/designSystem/components/page-header.md) - [Pagination](https://kwark.space/designSystem/components/pagination.md) - [Progress steps](https://kwark.space/designSystem/components/stepper.md) - [Side navigation](https://kwark.space/designSystem/components/side-navigation.md) - [Tabs](https://kwark.space/designSystem/components/tabs.md) - [Top bar](https://kwark.space/designSystem/components/top-bar.md) - [Tree view](https://kwark.space/designSystem/components/tree-view.md) ### Feedback - [Banner](https://kwark.space/designSystem/components/banner.md) - [Callout](https://kwark.space/designSystem/components/callout.md) - [Empty state](https://kwark.space/designSystem/components/empty-state.md) - [Feedback control](https://kwark.space/designSystem/components/feedback-control.md) - [Inline notice](https://kwark.space/designSystem/components/inline-notice.md) - [Offline state](https://kwark.space/designSystem/components/offline-state.md) - [Page loader](https://kwark.space/designSystem/components/cinematic-loader.md) - [Progress and loading](https://kwark.space/designSystem/components/progress.md) - [Skeleton](https://kwark.space/designSystem/components/skeleton.md) - [Spinner](https://kwark.space/designSystem/components/spinner.md) - [Status dot](https://kwark.space/designSystem/components/status-dot.md) - [Sync status](https://kwark.space/designSystem/components/sync-status.md) - [Toast](https://kwark.space/designSystem/components/toast.md) ### Overlays - [Context menu](https://kwark.space/designSystem/components/context-menu.md) - [Dialog](https://kwark.space/designSystem/components/dialog.md) - [Drawer](https://kwark.space/designSystem/components/drawer.md) - [Menu](https://kwark.space/designSystem/components/menu.md) - [Popover](https://kwark.space/designSystem/components/popover.md) - [Sheet](https://kwark.space/designSystem/components/sheet.md) - [Tooltip](https://kwark.space/designSystem/components/tooltip.md) ### Layout - [Accordion](https://kwark.space/designSystem/components/accordion.md) - [Card](https://kwark.space/designSystem/components/card.md) - [Divider](https://kwark.space/designSystem/components/divider.md) - [Toolbar](https://kwark.space/designSystem/components/toolbar.md) ### Data display - [Badge](https://kwark.space/designSystem/components/badge.md) - [Budget top sheet](https://kwark.space/designSystem/components/budget-top-sheet.md) - [Code block](https://kwark.space/designSystem/components/code-block.md) - [Dailies day](https://kwark.space/designSystem/components/dailies-day.md) - [Data table](https://kwark.space/designSystem/components/data-table.md) - [Description list](https://kwark.space/designSystem/components/description-list.md) - [Element tag](https://kwark.space/designSystem/components/element-tag.md) - [Keyboard key](https://kwark.space/designSystem/components/keyboard-key.md) - [List row](https://kwark.space/designSystem/components/list-row.md) - [Meter](https://kwark.space/designSystem/components/meter.md) - [Stat](https://kwark.space/designSystem/components/stat.md) ### Data visualisation - [Area chart](https://kwark.space/designSystem/components/area-chart.md) - [Bar chart](https://kwark.space/designSystem/components/bar-chart.md) - [Dailies frame](https://kwark.space/designSystem/components/dailies-frame.md) - [Donut chart](https://kwark.space/designSystem/components/donut-chart.md) - [Gantt chart](https://kwark.space/designSystem/components/gantt-chart.md) - [Line chart](https://kwark.space/designSystem/components/line-chart.md) - [Production timeline](https://kwark.space/designSystem/components/production-timeline.md) - [Scene density heatmap](https://kwark.space/designSystem/components/heatmap.md) - [Sparkline](https://kwark.space/designSystem/components/sparkline.md) - [Story spine](https://kwark.space/designSystem/components/story-spine.md) ### Media - [Bin](https://kwark.space/designSystem/components/bin.md) - [Compare viewer](https://kwark.space/designSystem/components/compare-viewer.md) - [Lightbox](https://kwark.space/designSystem/components/lightbox.md) - [Location card](https://kwark.space/designSystem/components/location-card.md) - [Media grid](https://kwark.space/designSystem/components/media-grid.md) - [Project cover](https://kwark.space/designSystem/components/project-cover.md) - [Source and program viewers](https://kwark.space/designSystem/components/viewer-pair.md) - [Storyboard frame](https://kwark.space/designSystem/components/storyboard-frame.md) - [Video player](https://kwark.space/designSystem/components/video-player.md) - [Waveform](https://kwark.space/designSystem/components/waveform.md) ### Creative tools - [ADR cue list](https://kwark.space/designSystem/components/adr-cue-list.md) - [Audio meter](https://kwark.space/designSystem/components/audio-meter.md) - [Breakdown page](https://kwark.space/designSystem/components/breakdown-page.md) - [Call sheet](https://kwark.space/designSystem/components/call-sheet.md) - [Camera setup card](https://kwark.space/designSystem/components/camera-inspector.md) - [Cast board](https://kwark.space/designSystem/components/cast-board.md) - [Channel strip](https://kwark.space/designSystem/components/channel-strip.md) - [Character card](https://kwark.space/designSystem/components/character-card.md) - [Character page header](https://kwark.space/designSystem/components/character-header.md) - [Clip inspector](https://kwark.space/designSystem/components/clip-inspector.md) - [Clips and grade versions](https://kwark.space/designSystem/components/grade-clip-strip.md) - [Colour curves](https://kwark.space/designSystem/components/colour-curves.md) - [Colour wheels](https://kwark.space/designSystem/components/colour-wheels.md) - [Edit timeline](https://kwark.space/designSystem/components/edit-timeline.md) - [Index card](https://kwark.space/designSystem/components/index-card.md) - [Looks and LUTs](https://kwark.space/designSystem/components/look-picker.md) - [Loudness meter](https://kwark.space/designSystem/components/loudness-meter.md) - [Marker list](https://kwark.space/designSystem/components/marker-list.md) - [Mixer](https://kwark.space/designSystem/components/mixer.md) - [Node graph](https://kwark.space/designSystem/components/node-graph.md) - [Outline board](https://kwark.space/designSystem/components/outline-board.md) - [Parametric EQ](https://kwark.space/designSystem/components/parametric-eq.md) - [Playhead and scrubber](https://kwark.space/designSystem/components/playhead.md) - [Production calendar](https://kwark.space/designSystem/components/production-calendar.md) - [Quick note](https://kwark.space/designSystem/components/quick-note.md) - [Screenplay elements](https://kwark.space/designSystem/components/screenplay-elements.md) - [Screenplay page](https://kwark.space/designSystem/components/screenplay-page.md) - [Script timeline](https://kwark.space/designSystem/components/script-timeline.md) - [Shot card](https://kwark.space/designSystem/components/shot-card.md) - [Sound tracks](https://kwark.space/designSystem/components/sound-tracks.md) - [Stripboard strip](https://kwark.space/designSystem/components/stripboard-strip.md) - [Timecode display](https://kwark.space/designSystem/components/timecode.md) - [Transport bar](https://kwark.space/designSystem/components/transport-bar.md) - [Video scopes](https://kwark.space/designSystem/components/video-scopes.md) ### AI and authorship - [Agent activity](https://kwark.space/designSystem/components/agent-activity.md) - [Agent plan](https://kwark.space/designSystem/components/agent-plan.md) - [AI consent prompt](https://kwark.space/designSystem/components/ai-consent.md) - [AI result review](https://kwark.space/designSystem/components/ai-review.md) - [AI undo history](https://kwark.space/designSystem/components/ai-undo-entry.md) - [Prompt input](https://kwark.space/designSystem/components/prompt-input.md) - [Provenance label](https://kwark.space/designSystem/components/provenance-label.md) - [Revision mark](https://kwark.space/designSystem/components/revision-mark.md) - [Suggestion panel](https://kwark.space/designSystem/components/suggestion-panel.md) ### Collaboration - [Avatar](https://kwark.space/designSystem/components/avatar.md) - [Board column](https://kwark.space/designSystem/components/board-column.md) - [Comment pin](https://kwark.space/designSystem/components/comment-pin.md) - [Comment reaction](https://kwark.space/designSystem/components/comment-reaction.md) - [Notification bell](https://kwark.space/designSystem/components/notification-bell.md) - [Presence cursor](https://kwark.space/designSystem/components/presence-cursor.md) - [Research card](https://kwark.space/designSystem/components/research-card.md) - [Script revision diff](https://kwark.space/designSystem/components/script-revision-diff.md) - [Version history](https://kwark.space/designSystem/components/version-history.md) ## Rules for agents > **For agents:** - **Must** use the component that exists before writing a new one; search this catalogue and `components.json` first. > - **Must** pick the variant named for the place you are building (a module page uses the story-surface button; Home’s blue is only for New project and Sign in). > - **Never** copy an older style a page lists under *Moving older code over*. > - **Never** present a Ready for Kwark component as something the app already has. ## Find a workflow [Screenwriting](https://kwark.space/designSystem/kits/screenwriting.md), [Scheduling and call sheets](https://kwark.space/designSystem/kits/scheduling-and-call-sheets.md), [Editing](https://kwark.space/designSystem/kits/editing.md), and [Building with agents](https://kwark.space/designSystem/agents/index.md) show how these parts work together. ## AI readiness test **Task:** Build the footer of the date editor in Prepare to shoot: delete, cancel and save. **Give the agent:** This page, Button, Dialog. **Constraint:** The dialog is a story dialog in a module. **A reliable answer:** - Uses the story-surface buttons (36px, 6px corners, 12px) - Delete at the far left, Cancel then Save at the right with Save primary - No Home blue - No upper-case labels --- # Contributing > How to propose a change to the Kwark system, write the decision record, get it reviewed, and what every control must meet before it is called done. Source: https://kwark.space/designSystem/contributing ## What counts as a change to the system - A new component, variant, token or pattern. - A change to a rule on any page, or to a value in `kwark.css`. - A screen in the app that does something the system does not cover yet. That is a gap, and the gap is the contribution. Fixing a typo or making a page match the app as it already is does not need a proposal. Say what you corrected in the pull request. ## Propose Write the proposal before you design anything final. It answers four questions, and it is short: 1. **Who needs this, in what situation?** One sentence, from how they actually work. "Mira is on set with a phone and needs to mark a take without leaving the call sheet." 2. **What happens to them without it?** If nothing does, stop. 3. **What already exists?** Name the components and patterns you checked, and why none of them does the job. If two things look different but do the same job, one of them is wrong. 4. **What would make us remove it?** The evidence that would tell us it is not helping. "A competitor has it" is never the answer to the first question. Competitors set the floor: say what this does that none of them do. See [Competitors are the floor](https://kwark.space/designSystem/method/competitors-are-the-floor.md). For anything larger than a part, walk the journey and draw the wireframe at phone size first, then desktop, before you build. See [UX before build](https://kwark.space/designSystem/method/ux-before-build.md). ## Write the decision record Every accepted change has a record in `docs/ux/decisions/`, one numbered file per decision (`0046-short-title.md`). Take the next free number. This is the template Kwark uses, as it is in the repository: ```markdown # NNNN · Title - **Status:** Accepted | Draft (rationale to confirm) | Under review | Superseded by NNNN | Removed - **Date:** YYYY-MM-DD - **Source:** who said or decided this, and where it is recorded (a note, a commit, a doc) ## Problem Who has it, in what situation, in their own words where we have them. ## Why this needs to exist What happens to the person if we do nothing. ## Alternatives we considered At least two, with why each was not chosen. ## Decision What we built or chose, in plain words. ## Why this is the best solution Tied to the principles (docs/ux/mission-and-principles.md). Name the principle. ## Every element, and what it means The screen's parts, including dots, badges, counts and colours (each also in the element register). ## What would make us remove it The evidence that would tell us this is not helping. ## Open questions and history Dated one-line notes; what changed and why. ``` A record starts as **Draft** and becomes **Accepted** only when the product owner accepts it. When a decision changes, add a dated line to its history instead of rewriting the past. See [Decision records](https://kwark.space/designSystem/method/decision-records.md). The [kwark-decision-record skill](https://kwark.space/designSystem/agents/skills.md) writes one with an agent. ## Every control says what it is This is the rule most often broken, and the one people notice first. Kwark wrote it down after a phone menu shipped as plain text with a bare "⋯", no icons and no chevrons. - **Must** give every control a word, or an icon with a word. Icon-only is for universal glyphs (back, close, more, add, search) and always has an accessible name that includes its object: "Close scene 12", "More actions for Act 2". - **Must** show a chevron on anything that opens something: ▸ opens a page or a flyout, ▾ opens a dropdown. - **Never** label a menu with "⋯" alone in a header. The word is **Menu**. - **Always** use the shared component (`Button`, `IconButton`, `TextButton`, `Sheet`, `ListRow`) so the label, the size and the focus ring come with it. ## Review A change is not done when it works. It is done when it has been looked at, reviewed by someone who did not build it, and fixed. 1. **Built from the system.** Shared components; tokens only; icons at 14, 16 or 20; 44px tap targets on phones. 2. **Looked at.** Screenshots at 1440, 768 and 375 wide, and 320 for headers, zoomed in. Alignment, clipping, centring, and every state: hover, focus, checked, disabled. Light, dark and the writing rooms where it applies. 3. **Two reviewers, review-only.** A **UI reviewer** checks system use, alignment, spacing, icons, labels, contrast in every room and clipping. A **UX reviewer** walks the person's journeys: plain names, one home for each command, nothing lost from the old design, shortcuts that really work. Other reviewers join when the change touches them: security for anything about sharing or data, a producer for anything that leaves the script, an engineer for types, tests and performance. 4. **Fixed, then re-checked** by the same reviewer. A finding is never dismissed without a written reason in the decision record. 5. **Recorded.** Decision record updated, element register updated for any new dot, badge, count or colour, tests and build green. > At Kwark the reviewers are separate agents running on the strongest model available (Opus), with review-only instructions, and creative work (look, wording, layout) is done or reviewed at that level rather than left to a cheaper default. A human reviewer is just as good. What matters is that the reviewer did not build it and is not allowed to fix it themselves. The [kwark-ux-review skill](https://kwark.space/designSystem/agents/skills.md) sets an agent up as a review-only supervisor with this checklist. ## Pull requests to the system itself - Prose pages are in `design-system/content/`, components in `design-system/components*.mjs`, styles in `design-system/css/`. - Component CSS uses only `--k-*` tokens and `kw-` classes. A new token goes in `:root` with a comment, and a light and a dark value taken from the app. - Run `node design-system/build.mjs` and check the page and its `.md` twin. - Every foundation, pattern, kit and component page ends with an AI readiness test. Add one for anything new. See [Readiness tests](https://kwark.space/designSystem/agents/readiness.md). ## AI readiness test **Task:** Propose a new "Take marker" component for marking takes from the call sheet on a phone, and write its decision record. **Give the agent:** This page, Decision records, components.json, Patterns: phones. **Constraint:** Check existing components first and name them. Leave the status as Draft. **A reliable answer:** - Names the person and situation in one sentence - Lists the components checked and why none fits - Gives at least two alternatives with reasons - Fills every section of the template - Says what would make us remove it - Every control has a word or a named icon --- # Designing with the system > How a designer works with the Kwark system - foundations first, then components and patterns, the journey before any build, a decision record for every choice and a review with screenshots. Source: https://kwark.space/designSystem/designing ## Start from the foundations Read the [Basics](https://kwark.space/designSystem/foundations/color.md) once, properly: colour roles, type scale, spacing, radius, elevation, layout, motion and icons. They are short. Almost every argument about a screen is settled by one of them: which surface, which size, how much space, whether it floats. Then read the three foundations that make Kwark different from a general system: - [Principles](https://kwark.space/designSystem/foundations/principles.md): the writer first, private and safe, no judgement of the writing, structure optional, paper and digital as one act. Each has a test you can run on your design. - [Writing rooms](https://kwark.space/designSystem/foundations/rooms.md): the five rooms a writer chooses for the screenplay editor. Anything you design that can appear inside the editor must work in all five. - [AI and authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md): how machine suggestions are shown and accepted, and what a machine is never allowed to do. ## Then components, then patterns Look for the part before you draw one. The [component catalogue](https://kwark.space/designSystem/components.md) shows each part live, with its states, its tokens and the words it uses. If two things look different but do the same job, one of them is wrong. For anything bigger than a part, read the [pattern](https://kwark.space/designSystem/patterns.md) first. Saving and sync, errors, empty states, phones, menus and shortcuts, destructive actions and sharing by role are already decided. Designing them again from scratch produces a second answer, and the app then has two. **Do:** Open the Menu component page, take its geometry and states, and design the new Scene menu inside it. **Don't:** Draw a fresh dropdown for one screen with its own corner radius, shadow and row height. ## The Kwark method: UX before build Nothing a person will see is built until four things are done and agreed. This is [UX before build](https://kwark.space/designSystem/method/ux-before-build.md), and it applies to designers and to agents alike. 1. **Is it needed?** Name the person, the situation and the problem in one sentence, from how they actually work. "A competitor has it" is not a reason; competitors are [the floor](https://kwark.space/designSystem/method/competitors-are-the-floor.md), not the goal. 2. **The journey.** Walk the whole path: where they come from, what they see at each step, what they do, what can go wrong, how they get back to writing. 3. **A wireframe, phone first.** Draw it at 375 wide, then desktop. Include the empty, loading, error and offline states. Count what competes for attention above the fold. 4. **Agreement.** The product owner confirms the journey and the wireframe. Open questions are asked, never silently defaulted. Only then build, in small steps. Ask two or three questions, state your calls, and show something: long rounds of discovery questions wear people out. ## Write the decision down Every UI decision gets a record: one numbered file that says the problem, the alternatives, what was chosen, why, what every element on the screen means, and what evidence would make us remove it. See [Decision records](https://kwark.space/designSystem/method/decision-records.md) and the template on [Contributing](https://kwark.space/designSystem/contributing.md). Every small thing that carries meaning (a dot, a badge, a count, a colour) also gets a line in the element register: what it means, when it appears and what the person is meant to do about it. A dot with no reason is removed. ## Review with screenshots "It works" is not done. A screen is looked at, not only run. - Screenshots at 1440, 768 and 375 wide, and 320 for headers. Zoom in. Check alignment, clipping, centring and every state: hover, focus, pressed, checked, disabled. - Check it in light, dark and the five writing rooms if it can appear in the editor. - Then a review by someone who did not build it: a UI reviewer for the system (tokens, alignment, labels, contrast) and a UX reviewer for the journey (plain names, nothing lost, shortcuts that are real). See [Review and quality](https://kwark.space/designSystem/method/review-and-quality.md). ## Handing off Write the spec so someone can build it without asking a question: parts by component name, values by token, every state, every string, phone and desktop separately, keyboard and accessible names, edge cases. The template is on [Handoff](https://kwark.space/designSystem/agents/handoff.md); it works for a human engineer and for an agent. ## Figma There is no Kwark Figma library yet. It is planned; see [Releases](https://kwark.space/designSystem/releases.md). Until then, design in whatever tool you like and name things by their component and token, so the handoff maps one to one. The live pages here are the reference for how each part looks: they render the real CSS. > Do not trace components from screenshots into a design file and treat that as the source. The source is the component page and `kwark.css`. A traced copy drifts the first time a value is corrected. ## AI readiness test **Task:** Plan the design of a new "Scene notes" panel for the screenplay editor, from problem to handoff. **Give the agent:** This page, UX before build, Writing rooms, Patterns: phones. **Constraint:** No pixels or hex values; name components and tokens. Phone first. **A reliable answer:** - Starts with the person and problem in one sentence - Walks the journey before any layout - Gives a phone layout and a desktop layout - Lists empty, loading, error and offline states - Checks the five writing rooms - Ends with a decision record and a review with screenshots --- # Developing with the system > How to use kwark.css and tokens.json in any codebase, which React components exist in the Kwark app and where to import them, the tests that keep the code inside the system, and how to theme with dark mode, writing rooms and a project accent. Source: https://kwark.space/designSystem/developing ## Two ways in - **Any codebase:** link `kwark.css`. It is one file with every token and the framework-free `kw-` component styles. No build step, no JavaScript. - **The Kwark app:** use the React components in `components/ui/`. They are the source of truth; the `kw-` CSS on this site reproduces them. Both read the same `--k-*` tokens, so a screen built from one and a panel built from the other sit together without a seam. ## kwark.css ```html ``` Or copy the file into your repository and serve it yourself; it has no dependencies. It is assembled from `design-system/css/*.css` in name order: the tokens first (`00-core.css`), then component styles. `kwark.css` does not load fonts. Load the three families the roles name, or the roles fall back to the system font: ```html ``` Put `kw-root` on the element that holds the interface. It sets the UI font, the body size, the text colour and the page colour: ```html ``` Every component page has the HTML under **Code**. Copy it as it is; the classes, the `type` attribute and the accessible names are part of the component. > **For agents:** In a codebase without React components from Kwark, build with the kw- HTML from the component page and the --k-* tokens. Do not restyle kw- classes with new values; if a variant is missing, say so. ## tokens.json `https://kwark.space/designSystem/tokens.json` publishes the light theme, dark theme and five rooms as DTCG 2025.10 tokens. Each theme includes inherited values. Colours use sRGB components, dimensions carry units, durations carry milliseconds, and aliases identify another token in the same theme. ```json { "light": { "k-space-2": { "$type": "dimension", "$value": { "value": 8, "unit": "px" }, "$extensions": { "org.kwark.css": { "value": "8px" } } } } } ``` Use the typed value for a native platform. The `org.kwark.css.value` extension preserves the exact CSS declaration, including `var()`, `clamp()` and safe-area expressions. For responsive or safe-area dimensions, the typed value supplies the first absolute size as a fallback. A native adapter must implement the responsive and safe-area behavior for its platform. The format follows the Design Tokens Community Group’s published exchange format. [DTCG format specification](https://www.designtokens.org/tr/2025.10/format/). ## React components in the Kwark app The app imports through the `@/` alias (the repository root). The barrel file `components/ui/index.ts` exports the most common ones: ```tsx import { Button, Modal, Input, Select, Tabs, Card, Badge, DropdownMenu, Drawer, EmptyState, UserAvatar } from '@/components/ui'; ``` Other components are imported from their own files. Consult the Code tab for the source referenced by each page: | Component | Import | |---|---| | Button | `import Button from '@/components/ui/Button'` (variants primary, secondary, ghost, danger; sizes sm, md, lg) | | Breadcrumb | `import { Breadcrumb } from '@/components/ui/Breadcrumb'` | | Toast | `import { useToast } from '@/components/ui/Toast'` (inside `ToastProvider`) | | ConfirmDialog | `import ConfirmDialog from '@/components/ui/ConfirmDialog'` | | ReadOnlyBanner | `import { ReadOnlyBanner } from '@/components/ui/ReadOnlyBanner'` | | ViewToggle | `import { ViewToggle } from '@/components/ui/ViewToggle'` | | Textarea, ContextMenu, TabBar, SectionLabel | `@/components/ui/` | The phone and chrome parts: | Component | Import | |---|---| | IconButton | `import IconButton from '@/components/ui/IconButton'` (a `label` prop is required; it becomes the accessible name) | | TextButton | `import TextButton from '@/components/ui/TextButton'` | | Icon | `import { Icon } from '@/components/ui/Icon'` (sizes sm 14, md 16, lg 20) | | Segmented | `import Segmented from '@/components/ui/Segmented'` | | Chip, ListRow, Sheet, MenuSheet, Combobox | `@/components/ui/` | | PageHeader (phone header and the floating dial) | `import PageHeader from '@/components/ui/PageHeader'` | | ProjectModuleBreadcrumb | `import ProjectModuleBreadcrumb from '@/components/ui/ProjectModuleBreadcrumb'` | Each component page names its import when it is in the app. If a page says **Ready for Kwark**, there is no React component yet: build it from the page's HTML and tokens, in `components/ui/`, and add it to that page in the same change. ## Theming ### Dark Add `class="dark"` (or `data-theme="dark"`) to ``. Every role switches; components need no change. In the Kwark app, `ThemeContext` sets both the class and `data-theme` on ``. The app opens in dark, and uses light only when the person chooses it, because the app's light theme is still being finished. `kwark.css` defaults to light; a product built on it can follow the system setting. ### Writing rooms Inside the screenplay editor the writer chooses one of five rooms. Put `data-room` on the container that holds the page: ```html

INT. EDIT SUITE – NIGHT

``` The values are `studio`, `daylight`, `paper`, `lamplight` and `midnight`. Inside a room the surface roles take the room's values, `--k-accent` becomes the room's pencil (`--k-pencil`), and `--k-on-accent` becomes the room's desk colour. A shared component placed inside the editor takes the room's colours with no extra code. See [Writing rooms](https://kwark.space/designSystem/foundations/rooms.md). ### A project's accent A writer can give a project its own colour, and it replaces the accent everywhere in that project. Set the accent and the colour that reads on it together, always: ```css .project-blank-pages { --k-accent: #2f6f5e; --k-on-accent: #ffffff; } ``` In the Kwark app this is `applyProjectAccent` in `utils/projectAccent.ts`. It sets the accent before the first paint (so a project never flashes the default colour), always sets the readable text colour with it, and treats the old imposed blues as no choice at all. `styles/tokens.css` maps `--k-accent` to that value, so components only ever read `--k-accent`. **Do:** Test a new component with a pale project accent and a dark one, and check the text on the accent in both. **Don't:** Assume the accent is copper, or write white text on the accent without `--k-on-accent`. ## Enforcement The system is enforced in the build, the way a linter enforces a code style. Each check runs with the app's test suite and fails the change that breaks it. - **`tests/design-system.test.cjs`** counts, per file, the places the code steps outside the system: a font named in a component (`fontFamily`), text under 11px (`tinyText`), a colour literal (`rawColour`), an icon size off 14, 16 or 20 (`iconSize`), and a pixel font size instead of the scale (`rawFontSize`). It fails when any file has more than its baseline allows, or a new file has any. Counts can only go down. - The same file checks that the tokens live in `styles/tokens.css` and are not redefined in `index.html`, and that every breadcrumb renders through `components/ui/Breadcrumb.tsx`. - **`tests/design-baseline.json`** holds the allowed counts. After a clean-up, lock the lower counts in with `node scripts/design-baseline.cjs`. Never run it to excuse a new violation. - The scan itself is `tests/support/designScan.cjs`. Colour literals are allowed only in `styles/tokens.css`, `index.html` and the editor's room file `editorTheme.ts`. - `docs/design-system.md` is the one-page summary of the rules the tests enforce. The [MCP server](https://kwark.space/designSystem/agents/mcp.md) runs a similar check (`audit_code`) on a snippet before it is committed, for code that is not yet in a branch. ## Before you open a pull request - Search the diff for `#`, `rgb(`, `px` font sizes and font names, and replace them with tokens. - Look at the screen at 1440, 768, 375 and 320 wide. On a phone, check the touch layout with a mobile device mode, not only a narrow window. - Tab through it: every control reachable, focus visible, Escape closes menus and dialogs, focus returns to the trigger. - If you changed what a person sees, add a decision record or a line to an existing one. See [Contributing](https://kwark.space/designSystem/contributing.md). ## AI readiness test **Task:** Add a "Rename scene" dialog to a React app that is not Kwark, using the Kwark system, then make it follow a project accent and the Paper room. **Give the agent:** This page, the Dialog and Text input component pages, tokens.json. **Constraint:** No Kwark React imports (they are not available outside the app). No new colours. **A reliable answer:** - Links kwark.css and loads the fonts - Uses the kw- dialog and input HTML with type and accessible names - Sets --k-accent with --k-on-accent together - Uses data-room="paper" on the container rather than new values - Returns focus to the trigger on close --- # Frequently asked questions > Short answers about using the Kwark system - licensing (MIT code, CC BY writing), Figma, React or plain CSS, using it outside film, agents, status labels, contributing and what is not covered yet. Source: https://kwark.space/designSystem/faq ## About the system ### What is the Kwark Design System? The rules, parts and patterns that Kwark, a story workspace for filmmakers, is built from, published for people and for the agents that build with them. See [About](https://kwark.space/designSystem/about.md). ### Is this a theme for Kwark, or the real thing? The real thing. Components are reproduced from Kwark's source with the same geometry, type, colours, states and words, and rules cite the decisions they come from. Where Kwark does not have a part yet, the page says **Ready for Kwark**. ### Who decides what goes in? Kwark's founder accepts decisions; anyone can propose one. Every accepted change has a decision record that says why. See [Contributing](https://kwark.space/designSystem/contributing.md). ### What do In the app, Ready for Kwark and New mean? **In the app**: the component is in Kwark's code, and the page gives its React import. **Ready for Kwark**: specified to the same standard, not yet in the app, so there is no React component. **New**: added or changed in this release. See [About](https://kwark.space/designSystem/about.md). ## Using it ### What licence is it under? Code is MIT, the writing is CC BY 4.0, and the Kwark name and brand are not licensed. You can ship `kwark.css` in a commercial app if you keep its notice; you can reuse the rules with credit; you cannot call your product Kwark. The full terms are on [Licence](https://kwark.space/designSystem/licence.md). ### Can I use it for a product that has nothing to do with film? The parts and foundations work for any product, and the patterns for saving, errors, empty states and phones are general. But the system is opinionated for creative work: it assumes the person's work is private, never judged, and that structure is optional. If your product needs leaderboards, streaks or scores, it will fight you. Once the licence is decided, that will also say what is allowed. ### Is there a Figma library? Not yet. It is planned and will be built from `tokens.json` so the values match. Until then, the live pages are the visual reference, and a design that names components and tokens hands off cleanly. See [Designing](https://kwark.space/designSystem/designing.md). ### Should I use the React components or plain CSS? Inside the Kwark app, the React components in `components/ui/`: they are the source of truth. Anywhere else, `kwark.css` and the `kw-` HTML from each component page: there is no published React package. Both read the same tokens. See [Developing](https://kwark.space/designSystem/developing.md). ### Does it work with Vue, Svelte, plain HTML or a native app? Yes, through `kwark.css` and the `kw-` HTML for web frameworks, and through `tokens.json` for native apps (Swift, Kotlin) or a Tailwind theme. Interactive behaviour (menus, dialogs, focus) you write yourself, following each page's Accessibility tab. ### Why do the fonts not load? `kwark.css` does not load fonts. Load Poppins, Raleway and Courier Prime yourself; the snippet is on [Developing](https://kwark.space/designSystem/developing.md). ### How do dark mode, writing rooms and project colours work? `class="dark"` on `` for dark. `data-room="studio|daylight|paper|lamplight|midnight"` on the working surface for a writing room. A project's colour is `--k-accent` set together with `--k-on-accent`. Components need no changes for any of them. See [Developing](https://kwark.space/designSystem/developing.md) and [Writing rooms](https://kwark.space/designSystem/foundations/rooms.md). ### Why is Kwark itself dark when the system defaults to light? The app's light theme is still being finished, so Kwark opens in dark and uses light only when someone chooses it. The light values on this site are specified; not every app screen uses them yet. ### Can I add my own tokens or colours? Add a token only when no role fits, with a light and a dark value and a comment, and propose it so it can join the system. Never write a raw colour into a component. See [Colour](https://kwark.space/designSystem/foundations/color.md). ### Does it cover Indian scripts? Yes. Writers in Kwark type in Hindi, Tamil and other Indian scripts. See [Writing systems](https://kwark.space/designSystem/foundations/writing-systems.md) for type, input and how those scripts print. ## Agents ### Which file should I give an agent? `AGENTS.md` always, then the markdown twins of the pages the task touches. Not `llms-full.txt` for a single screen. See [AI context files](https://kwark.space/designSystem/agents/ai-context.md). ### How do I get a page as markdown? Add `.md` to its URL, or switch the page to **Agent** and press **Copy markdown**. ### Which agents does it work with? Any agent that can read a file or a URL. The [quick start](https://kwark.space/designSystem/agents/index.md) covers Claude Code, Cursor, Codex and Gemini; the [MCP server](https://kwark.space/designSystem/agents/mcp.md) works with any client that speaks the Model Context Protocol. ### Do I need the MCP server? No. It helps an agent look things up and check its own code while it works, but `AGENTS.md` and the right page twins are enough for most tasks. ### Does the MCP server send my code anywhere? No. `audit_code` runs on your machine. If the server has no local copy of the site, it fetches the public files from kwark.space; your code is never sent. ### What are the skills, and do I have to use Claude? Each skill is a `SKILL.md` file that tells an agent how to do one job the Kwark way. Claude Code loads them automatically; other agents can be given the file as a prompt or a rule. See [Skills](https://kwark.space/designSystem/agents/skills.md). ### How do I know an agent is really following the system? Run the readiness test at the end of a page in a fresh conversation and grade each item as met or not met. See [Readiness tests](https://kwark.space/designSystem/agents/readiness.md). ### Will an agent using this write AI features that judge people's work? It should refuse to. The rules say a machine suggests and a person writes, that suggestions are marked until accepted, and that nothing scores or grades a person's story. See [AI and authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md). ## Contributing and versions ### How do I report a page that does not match the app? Say the page, what the app does, what the page says, and the theme or room you saw it in. A screenshot helps. See [Contributing](https://kwark.space/designSystem/contributing.md). ### How do I propose a new component? Say who needs it and in what situation, which existing components you checked and why none fits, and what would make us remove it. Then write the decision record. See [Contributing](https://kwark.space/designSystem/contributing.md). ### How is it versioned? One number for the whole system: pages, `kwark.css`, `tokens.json`, `components.json`, the MCP server and the skills. Token names do not change inside a major version. See [About](https://kwark.space/designSystem/about.md) and [Releases](https://kwark.space/designSystem/releases.md). ### Are the guides available? Not yet. They are planned as paid guides; there is nothing to buy or sign up for. See [Guides](https://kwark.space/designSystem/guides.md). ## AI readiness test **Task:** A startup asks whether they can ship kwark.css in their commercial screenwriting app and design in Figma with it. **Give the agent:** This page. **Constraint:** Only what this page says. **A reliable answer:** - Says kwark.css can ship commercially under MIT with its notice kept, and points to the Licence page - Says there is no Figma library yet and it is planned - Points to the live pages and tokens.json as the reference - Does not invent licence terms --- # Accessibility > WCAG 2.2 AA is the floor. This page gives Kwark's contrast per role, the keyboard map for the screenplay, timeline and boards, focus, screen readers, targets, motion, zoom, media and the checks every change must pass. Source: https://kwark.space/designSystem/foundations/accessibility ## The floor and the target Kwark meets **WCAG 2.2 level AA** everywhere a person can go: the app, the published site, print and PDF, and this design system. That is the floor, not the goal. Where the thing on screen *is* the work (the script, the call sheet a crew reads at 6am), Kwark aims higher: 7:1 for the script's ink, and a stronger-contrast switch in every writing room. Accessibility here is not a checklist stage at the end. It is part of principle 11, *Works for everyone, everywhere*, and every screen runs the everyone test: phone, tablet, laptop; keyboard only; screen reader; slow or no network; a script in Tamil. > **For agents:** - **Must** meet WCAG 2.2 AA in light, dark and all five writing rooms. > - **Must** use native elements first: `button`, `a`, `input`, `select`, `dialog`, `details`. > - **Must** give every icon-only control an accessible name that includes its object ("More for day 3", not "More"). > - **Must** offer a keyboard and a single-pointer way to do anything that can be dragged. > - **Never** remove a focus outline without a visible replacement. > - **Never** carry meaning by colour alone. ## Contrast, role by role Measured with the WCAG formula on the token values in `kwark.css`. | Pair | Light | Dark | Needs | Notes | |---|---|---|---|---| | `--k-text` on `--k-surface` | 17.9:1 | 13.2:1 | 4.5:1 | Body and titles | | `--k-text-2` on `--k-surface` | 5.4:1 | 6.5:1 | 4.5:1 | Meta, captions, placeholders | | `--k-text-2` on `--k-bg` | 5.2:1 | 7.0:1 | 4.5:1 | Quiet text on the page | | `--k-on-accent` on `--k-accent` | 5.0:1 | 10.2:1 | 4.5:1 | Primary buttons with the default copper. A project accent recalculates `--k-on-accent` | | `--k-focus` on `--k-surface` | 17.9:1 | 15.0:1 | 3:1 | The focus ring | | `--k-rev` on `--k-rev-bg` | 4.1:1 | 8.9:1 | 4.5:1 | Revision label text. **Below AA in light at 12px.** Known gap | | `--k-line-strong` on `--k-surface` | 1.5:1 | 1.7:1 | 3:1 when it is the only boundary | **Known gap.** Field borders must not be the only thing that identifies a field | Writing rooms, measured on the values in `editorTheme.ts`: | Room | Ink on page | Ink on desk | Quiet text on chrome | Pencil on page | |---|---|---|---|---| | Studio | 13.9:1 | 15.4:1 | 7.2:1 | project colour | | Daylight | 17.2:1 | 14.2:1 | 6.6:1 | 6.6:1 | | Paper | 14.1:1 | 9.9:1 | 5.7:1 | 6.1:1 | | Lamplight | 12.2:1 | 14.0:1 | 7.4:1 | 7.4:1 | | Midnight | 13.3:1 | 15.0:1 | 7.6:1 | 7.7:1 | The rooms do not rely on hand-picked values. Quiet ink is faded toward its ground only as far as the worst of the grounds it sits on allows (5.2:1 for muted text, 3.2:1 for faint marks, 7:1 and 4.6:1 with Stronger contrast on). See [Writing rooms](https://kwark.space/designSystem/foundations/rooms.md) for the maths. ### Stronger contrast The room picker (View › Room…) has a switch, *Stronger contrast: Fuller ink and firmer lines, in whichever room.* It sets pure black or white ink, whichever measures better against all three grounds, and raises the quiet-text target to 7:1. It is the screen's equivalent of a heavier pen, and it works in any room, including one a writer mixed themselves. > **For agents:** - **Must** check text at 4.5:1 and icons, field borders and the focus ring at 3:1 against every ground they can sit on, not only the page. > - **Must** test any new colour in the Paper room (warm, mid-light) and with Stronger contrast on. > - **Never** fade text with `opacity`. Use `--k-text-2`; in the editor, the room's settled muted ink. ## Keyboard Everything that works with a pointer works from the keyboard. Kwark's keys come from one file in the screenplay (`utils/editorShortcuts.ts`): the menus show them beside each command, the shortcuts sheet (⌘/) lists them, and the keys do what the sheet says. Keys a browser keeps for itself (new tab, close, reload) are left alone. On Windows and Linux, ⌘ reads Ctrl and ⌥ reads Alt; labels are written for the platform (⌥⌘R on a Mac, Ctrl+Alt+R elsewhere). ### Screenplay editor | Keys | Does | |---|---| | Enter | New line; the next element follows screenplay convention (after a cue, dialogue) | | Tab · ⇧Tab | Cycle the current element forward or back (action, character, dialogue…) | | ⌘⇧1 to ⌘⇧9 | Make the line a scene heading, action, character, dialogue, parenthetical, transition, music, shot or lyrics. A writer can reassign the digits in Settings | | ( at the start of a dialogue line | Starts a parenthetical | | ⇧Enter | Break the line without changing the element | | ⌥↑ · ⌥↓ | Carry the line past its neighbour; the caret goes with it | | ⌘Z · ⌘⇧Z | Undo · Redo | | ⌘S | Says *Saved. Your script saves as you write.* (Decision 0014) | | ⌘⇧S | Make a restore point | | ⌘F · ⌘G | Find · Go to scene | | ⌘\\ | Show or hide the scene navigator | | ⌥⌘R | Read mode | | ⌘⇧F | Distraction-free | | ⌘⇧D | Dual dialogue | | ⌘⇧E | Export | | ⌘, · ⌘/ | Settings · Keyboard shortcuts | **Typing in an Indian script.** In a line whose speaker has a language, the word being typed is shown in that script just below the caret. Space, a punctuation mark or Enter writes it in; Esc keeps that word in Roman letters. The preview is zero width, so it never moves a line or a page break. See [Writing systems](https://kwark.space/designSystem/foundations/writing-systems.md). ### Tab belongs to the script In every screenplay tool, Tab cycles elements. Kwark keeps that convention, which means Tab cannot also move focus out of the page. WCAG 2.1.2 (No keyboard trap) allows this only if the way out is standard or is told to the person. - **Must** keep a documented key that moves focus from the page to the menu bar, and list it first on the shortcuts sheet. - **Must** announce, once, when the page takes focus, how to leave it (in the accessible description of the editor, not as a visible banner). - Status: the screenplay's exit key has not been verified in this pass. Treat this as open, and do not ship a new editor surface that captures Tab without it. ### Scenes, days and boards | Where | Keys | Does | |---|---|---| | Scene cards | ← → ↑ ↓ | Move focus between cards | | Scene cards | ⌥⇧ with an arrow | Carry the scene one place along | | Day planner (Schedule) | Enter or Space | Choose the block | | Day planner | ⌥↑ · ⌥↓ | Move the block earlier or later in the day | | Day planner | ⇧↑ · ⇧↓ | Shorten or lengthen the block by one step | | Day planner | Delete or Backspace | Remove the block | | Calendar | C · T · W · X · D · M · A · L · B · [ · ] · ? · Esc | Quick add, today, views, previous and next, shortcuts, close. Single keys are ignored while typing in a field or a dialog | | Timeline (desktop) | Tab, then Enter | Each scene is a button named *Scene 12, INT. EDIT SUITE – NIGHT, about 2:40* | | Timeline strip (phone) | Enter or Space | Opens the full timeline | **Known gap.** The phone timeline strip has `role="slider"` but answers only Enter and Space. A slider must also answer ← → (previous and next scene), Home and End. Until it does, the scene navigator and ⌘G are the keyboard routes. > **For agents:** - **Must** read keys from the shared shortcut table, show them in menus with `kbd`, and list them on the shortcuts sheet. > - **Must** ignore single-key shortcuts while focus is in a text field, the screenplay page or a dialog. > - **Never** bind a key a browser or screen reader reserves (⌘T, ⌘W, ⌘R, Ctrl+Alt arrows on Windows readers). ## Dragging always has another way WCAG 2.2 adds 2.5.7, *Dragging movements*: anything that can be dragged must also work with a single pointer, without dragging. Kwark already has these routes; new work follows them. | Drag | Single pointer | Keyboard | |---|---|---| | Reorder scene cards | Not verified in this pass | ⌥⇧ with an arrow | | Move a block in the day planner | Not verified in this pass | ⌥↑ · ⌥↓ | | Resize a block | Not verified in this pass | ⇧↑ · ⇧↓ | | Reorder episodes in a series | ⋯ › Move earlier / Move later | Through the menu | | Arrange a character's pages | Move up / Move down | Through the menu | | Move a line of the script | Cut and paste | ⌥↑ · ⌥↓ | | Create an event by dragging the calendar grid | Quick add, then the event inspector | C | Where a row says *Not verified*, the keyboard route exists in the source; a single-pointer route (a *Move earlier* / *Move later* item in the thing's ⋯ menu) is the rule to add if it is missing. - **Must** announce the result of a keyboard move in words ("Moved Scene 12 after Scene 13") through a polite live region. - **Must** keep focus on the thing that moved. ## Focus - **Ring.** 2px `--k-focus`, 2px offset, on `:focus-visible`. Inputs use a 1px offset and drop their border colour so the ring is the only edge. - **Not hidden** (2.4.11, new in 2.2). A focused control must not sit under the phone's floating dial or a sticky header. Pages keep `--k-fab-slot` free at their foot, and scrolling a focused element into view must clear both. - **Order** follows reading order. Never use a positive `tabindex`. - **Return.** Every dialog, sheet and menu returns focus to the control that opened it. Escape closes the top-most layer only. - **Into the work.** A rule for every view: on opening, focus goes to the view's heading, or in the screenplay to the caret where the writer left it. ## Screen readers Test with VoiceOver on macOS and iOS, TalkBack on Android, and NVDA on Windows for the core journey. - **Landmarks.** One `main` per view; the editor's panels are `region`s with names (*Estimated runtime*, *Top sheet*, *Shooting days*). - **The script.** A screen reader user must be able to tell a cue from a line: each element's type (scene heading, action, character, dialogue) must be exposed, not only drawn by indent. Verify this on every surface that renders the script. - **Language of a line.** A line written in Tamil or Hindi must carry `lang` (`ta`, `hi`) so the reader switches voice (3.1.2). Kwark stores the language per character and per line; exposing it as `lang` on the rendered line is a rule for every surface that shows the script. - **Measures, in words.** The timeline strip says *Runs about 1 h 42 min* and gives the current scene as its value text. The talk and action bar is `role="img"` named *Talk 62 percent, action 38 percent*. - **Save state.** The sync word is in a polite live region. Errors that block work (a change that could not be stored) use `role="alert"`, once. - **Toasts.** Polite, never assertive. A toast with an action (Undo) stays until it is used or dismissed by keyboard, never only on a timer. - **Revision marks.** The label *Suggested* is read before the suggested words (`aria-describedby`), so the tint is never the only signal. - **Decorative pieces.** Icons beside a word are `aria-hidden`. Sprocket holes on Dailies film strips and paper grain are decoration. ## Targets | Context | Minimum | Token | |---|---|---| | Phone and touch (≤767px, sideways phones) | 44 × 44px | `--k-tap` | | Desktop controls | 32px high | `--k-control-sm` | | WCAG 2.5.8 floor | 24 × 24px, or 24px spacing | none | Small marks that are not the only route are allowed under 2.5.8's equivalent-control exception: a 3px-wide scene on a 120-minute timeline is reachable through the scene navigator and ⌘G. Rows on a phone have no inline buttons; the whole row is the target and secondary actions are in its ⋯ sheet (Decision 0016). ## Motion Motion answers an action; there is no ambient animation in the app. Durations are `--k-dur-1` 120ms, `--k-dur-2` 200ms, `--k-dur-3` 320ms. Under `prefers-reduced-motion: reduce`, transitions and animations collapse to 1ms and loops stop. The timeline's current scene used to pulse with a glow and six rising particles. They are gone (Decision 0041), and the scene is marked with a 2px ring and a pointer. Scrubbing the phone strip gives a 4ms haptic tick per scene where the phone supports it; it is a bonus, never the only feedback. - **Never** animate the script page, the caret or the page count. - **Never** auto-play an animatic or a table read. ## Zoom and reflow **App zoom.** Settings has a zoom from 80% to 200% in 5% steps, kept on the device. It sets `--app-zoom` (default 1.2), which scales the root font size, so everything sized in `rem` follows it. On phones (≤767px) the multiplier is switched off and the root is a standard 16px, because the phone's own text size and pinch zoom do the job. **Page zoom.** The screenplay page has its own zoom (Fit width, or a page zoom). It changes how large the page is drawn, never the page's geometry: line breaks and page count are the same at every zoom. **Browser zoom.** At 200% and at 320 CSS pixels wide (1.4.10 Reflow), nothing is cut off and nothing scrolls in two directions, except the parts that are two-dimensional by nature: the timeline, the stripboard, the calendar time grid and the printed page. **Text spacing.** Line height 1.5, paragraph spacing 2×, letter spacing 0.12em and word spacing 0.16em (1.4.12) must not clip text. Use `min-height`, not `height`, on anything that holds words. ## Media, captions and transcripts - **Table reads.** A table read speaks the script with the device's voices. The script is its transcript. A rule for any reading view: show which line is being spoken, in text as well as by highlight. - **Animatics.** An animatic is built from the boards, so its frames and their descriptions are its text alternative. Any dialogue it plays must be shown as captions from the script. - **Video a person uploads** (research, references, audition tapes). Kwark does not support caption tracks on uploaded video yet. A rule for anything built: allow a `.vtt` file beside a video, and show *No captions* in words when there is none. - **Images.** A rule for anything built: every image a person uploads can carry a description, and boards and covers that carry the story say what they show. ## Forms and sign-in - **Labels** are visible and above the field. Placeholder text is never the label. - **Errors** say what happened and how to fix it, next to the field, and move focus to the first one (3.3.1, 3.3.3). - **Redundant entry** (3.3.7). Kwark's core idea is that one script feeds everything; never ask for what the project already knows. The call sheet takes cast from the breakdown and the budget takes fees from casting. - **Accessible authentication** (3.3.8). No puzzles or memory tests to sign in; password managers and paste must work. - **Consistent help** (3.2.6). Help sits in the same place in every view. In the screenplay it is the Help menu (Decision 0015); other views must keep it in one fixed place too. ## Who is responsible for what | Component | Must handle | |---|---| | Button, Icon button | Native `button`; accessible name with its object; `aria-pressed` for toggles; disabled controls explain why | | Menu, Dropdown | Arrow keys, Home, End, type-ahead; Escape closes and returns focus; shortcuts shown with `kbd` | | Dialog, Sheet | `dialog` or `role="dialog"` with `aria-modal`; focus trapped while open and returned after; Escape closes | | Toast | Polite live region; actions reachable by keyboard; no timer while focused or hovered | | Tabs, Segmented | Arrow keys move between options; `aria-selected` or `aria-pressed` | | Switch | `role="switch"` with `aria-checked`; the label says what is on | | Timeline | Scenes as named buttons; strip as a real slider; measures in words | | Screenplay page | Element types exposed; `lang` per line; a documented way out of Tab | | Revision mark | *Suggested* in words before the text; Accept, Edit and Revert by keyboard | | Charts | A name with the numbers, or a table beside the chart. See [Data visualisation](https://kwark.space/designSystem/foundations/data-visualization.md) | ## Checks before anything ships 1. Keyboard only: reach, use and leave every control; focus always visible and never hidden. 2. Screen reader: VoiceOver (macOS, iOS) and TalkBack on the changed journey; names, roles, states and live messages make sense alone. 3. Contrast: every new pair in light, dark and the five rooms, and with Stronger contrast on. 4. Zoom: 200% browser zoom, app zoom at 80% and 200%, and 320px wide. 5. Touch: a real phone, not a resized desktop window. Targets 44px; nothing only on hover. 6. Reduced motion on: nothing moves that does not have to. 7. Drag: every drag has a single-pointer and a keyboard route. 8. Language: a Tamil or Hindi line keeps its `lang` and does not clip its vowel signs. These checks are the agreed method. Recording which screens have passed them is part of the launch readiness work, not yet complete. **Do:** An icon button named *More for day 3*, a visible focus ring, and the same action in the row's ⋯ sheet on a phone. **Don't:** A bare ⋯ with no name, `outline: none`, and an action that only appears on hover. **Do:** A drag that also has *Move earlier* in the menu and ⌥⇧ with an arrow on the keyboard. **Don't:** A board that can only be rearranged by dragging cards with a mouse. ## AI readiness test **Task:** Add a "reorder shots" interaction to the shot list for Scene 12. **Give the agent:** This page, the Menu and List row components, the Day planner key map above. **Constraint:** Must meet WCAG 2.2 AA, including 2.5.7 Dragging movements and 2.4.11 Focus not obscured. **A reliable answer:** - Drag plus a single-pointer route (Move earlier, Move later in the ⋯ menu) - Keyboard route with ⌥ and an arrow, focus stays on the moved shot - Result announced in words through a polite live region - Focus ring visible and clear of the phone's floating dial - No colour-only state --- # AI and authorship > Kwark's stance on machines and the writer's work. What a machine may and may not do in Kwark, how anything it proposes is marked, sourced, consented to and undone, what happens to the work's privacy, and why Kwark chose the margin mark over the industry's sparkles and glows. Source: https://kwark.space/designSystem/foundations/ai-and-authorship ## The stance > Kwark never judges the script. No AI feedback, scores, verdicts or rewrites of the writer's work. The filmmaker stays the author. (Decision 0002) The founder's reason, in his words from the review that started it: "right now the industry has not understood how to use AI in scripting, and I want to be mindful". Competitors sell AI coverage, scores and generated reports. Kwark does not count those as gaps and does not build equivalents. Decision 0002's own remove condition is *never, unless the founder reopens it; competitors' AI features are not a reason.* This is not a stance against machines. It is a stance about **who the author is**. A machine in Kwark may help a person see their own work, find things in it, carry it into production and hand it to tools they choose. It may never tell them whether the work is good, and it may never put words into the work that the person did not choose. The specimen above is the real thing: the breakdown reading the page for what production needs. It is a guess, and the interface says so in every line. ## What runs in Kwark today Said plainly, so nobody overclaims: - **There is no generative model in the app.** The Kwark source has no AI model calls. Nothing in a project is written, rewritten, summarised or scored by a language model. - **Kwark does guess, in a few places, with rules on the device.** The breakdown reads capitals and a short list of nouns production must always account for. The calendar's quick add parses *Table read with Meera next Tue 7pm–9pm Sc 4, 7* locally, without a cloud call. Phonetic typing turns Roman letters into a script from tables and open-source engines (see [Writing systems](https://kwark.space/designSystem/foundations/writing-systems.md)). Table reads use the browser's speech voices. - **One opt-in sends text out.** Since Decision 0046, *Smart phonetic suggestions* asks an online dictionary input service for better candidates for the word being typed. It is off by default, and the setting says what it costs. - **The AI storyboard pack is agreed as an idea and not built.** It is described below because it is the model for how AI may enter Kwark. ## What a machine may do in Kwark | May | Example | Why it is allowed | |---|---|---| | Measure the work | *Runs about 1 h 42 min* · *Talk 62% · Action 38%* | It describes; it does not rate (principle 6) | | Find things in the work | The breakdown's *The script mentions* | Offered, never applied | | Carry the work into production | Scenes into the breakdown, breakdown into the schedule, cast into the call sheet | One script feeds everything, with nothing retyped | | Move the writer's own words between places | An outline beat title proposed as a scene heading (a pattern, not built) | The words are the writer's; only the place is proposed | | Convert how words are typed | *naan ingey irukken* to நான் இங்கே இருக்கேன் | The writer's words, in their script | | Read the work aloud | Table read with device voices | A performance of the text as written | | Prepare an export for a tool the person chooses | The AI storyboard pack | The person decides what leaves, and where | ## What a machine may never do in Kwark - **Score, grade or rate** the writing, a scene, a character or a writer, as a number, a colour, a badge or a word (Decision 0002). - **Give coverage**: no verdicts, no *pass/consider/recommend*, no strengths and weaknesses. - **Rewrite** the writer's words, or offer "improved" versions of their dialogue. - **Write into the work on its own.** Nothing a machine proposes is saved into the script, the outline or the breakdown until a person accepts it. - **Coach.** No prompts about what a character wants or what a scene should do (Decision 0004). - **Rank or compare** people, takes, drafts or projects (Decision 0001). - **Pick a winner**: no *best take*, *strongest draft*, *recommended ending*. - **Train on the work.** See [privacy](#the-work-is-not-training-data). The idea module's *Conviction %* and the outline's trophies are recorded as deviations to remove under this rule, as are AI-flavoured labels found in the audit. ## The revision mark When a machine does propose words or items, Kwark marks them with a [revision mark](https://kwark.space/designSystem/components/revision-mark.md): a soft tint, a dotted rule and an asterisk in the right margin, plus a label in words that says where they came from. Film already has this sign. In a revised shooting script, a changed line gets an asterisk in the right margin, and writers, directors and script supervisors read it as *this is new; look at it*. Kwark uses the same mark for anything a machine proposed. It needs no explanation, it survives printing (Decision 0005), and it is flat. ```html

INT. EDIT SUITE – NIGHT

* Suggested · from your outline, Act 2
``` ### The life of a mark 1. **Suggested.** Tinted, dotted rule, margin star, and a label saying where it came from. Nothing is saved into the work. 2. **Accepted.** The tint and the star go. The history keeps where it came from. 3. **Edited.** The moment a person changes the words, they are the person's. No mark. 4. **Dismissed.** It goes, and the same suggestion is not offered again. The breakdown keeps a list of dismissed suggestions so a *Not needed* stays not needed. 5. **Undone.** Accepting is one step in the history; Undo takes it back. A mark never outlives a person's edit. Kwark never shows *AI-written* on text a person has changed, and never keeps a percentage of how much of a script a machine proposed. ## Provenance: say where it came from Every suggestion carries its source and its reason, in words a person can disagree with. The breakdown's suggestion file says it in its own comments: every suggestion is a guess, offered and never applied, with a reason "in words a person can disagree with". | Part | In the breakdown | Rule | |---|---|---| | Source | *The script mentions* · *Read off the page, never assumed.* | Name where the material came from: the page, the outline, a file the person chose | | Reason | *Anything an actor handles has to be there on the day.* · *Set in capitals, the way an element is introduced.* | A plain sentence, not a confidence score | | Implied items | Something the action implies but the page never names (somebody writes, so there is something to write with) is offered as a guess to rename | Say when something is inferred rather than read | | Status | *Nothing here counts until you say so.* | Say that nothing has happened yet | | Count | *Suggestions waiting* | Neutral; never *missed* or *ignored* | ## Consent - **Per item, every time.** Each suggestion has its own *Add* and *Not needed*. There is no *Accept all* for words that go into the script. - **Batches say they can be changed.** When a person asks Kwark to make many things at once, the toast says so: *12 dates added. Each can be changed or removed.* - **Sending anything out is opt-in, off by default, and named.** The setting says what is sent and to whom, in its own line, before it is switched on. - **Students.** Kwark serves students from 13. Until the guardian-consent work in the launch plan exists, a rule for anything built: no feature that sends a student's work to an outside AI service. - **Nothing is assumed from a role.** Saying you are an actor never turns on a feature that reads your scenes. ## Undo Accepting a suggestion, adding a batch, converting a word: each is one step in the history and one Undo away. In the phonetic typing, Esc keeps the Roman word, and the editor remembers that choice for that word so it is not converted again. Every machine action must be at least as easy to reverse as it was to accept. ## The work is not training data Only what is true: - Kwark has no AI model, so Kwark does not train one on anyone's work. - Kwark does not send script text to an AI service today. The one opt-in that sends typed words out (*Smart phonetic suggestions*) sends the word being typed to an input service, and only when the writer turns it on. - Browser speech voices belong to the browser. Some browsers offer online voices; a rule for any reading feature: prefer voices the browser reports as local, and say when one is not. Rules for anything built: - **Never** use a person's work, or anything derived from it, to train or tune a model, unless that person has said yes to exactly that, for that project. - **Must** say, before anything leaves the device, which service receives it and what is sent. - **Must** keep the choice per project and reversible, and stop sending the moment it is turned off. ## The AI storyboard pack The model for how AI may enter Kwark: **exported, chosen and brought back by the person**, never generated inside Kwark. Agreed with the founder on 29 September 2026, not yet built (its journey still needs his agreement): - For a scene, Kwark exports a pack: a PDF, a zip of images, and a master prompt for whichever model the person picks. - The prompt makes that AI ask for character images and a location image (or offer to make them) before it draws, so the boards match the film's own people and places. Kwark prefills references from Casting and Locations photos before asking for uploads. - The person uploads the results back onto the board panels. - No generation happens in Kwark, and there is no API cost. Generating images on Kwark's servers would break the free-tier budget. - Like every script-bound module, the paper pack and the structured record are built in the same act (Decision 0005). Rules for when it is built: an uploaded panel image says where it came from (*Imported image*) until the person edits or replaces it, and the pack never includes material from people's private research unless the person adds it. Kwark's own 3D boards are a different thing: figures posed and lit by the person, baked to images. They are drawing tools, not generation. ## How the industry does it, and what Kwark chose | Industry pattern | What it does | Kwark's choice | |---|---|---| | Sparkle icon and *AI* badges | Marks a feature as AI, and sells it | No sparkles. Say the source in words: *from your outline*, *The script mentions* | | Purple gradients and glows around machine text | Makes machine text the brightest thing on the screen | Flat tint and a margin asterisk. Machine text is the *quietest* new thing on the page (no-glow rule, Decision 0041) | | Ghost text that completes your sentence | Writes as you type; Tab accepts | Not in Kwark. The writer's Tab is the screenplay's Tab, and the next words are the writer's | | Chat sidebar that can edit the document | A conversation that rewrites the work | Not in Kwark. Exports to a tool the person chooses | | *Why am I seeing this?* explainability popovers | Explains a recommendation after the fact | The reason is printed beside the suggestion, always visible, in one sentence | | Confidence scores (82% sure) | Presents a guess as a measurement | No percentages. A guess is labelled a guess | | Coverage, scores, *readiness* meters | Grades the script | Never (Decision 0002) | | *Accept all* | One click puts every suggestion into the work | Per item for anything that reaches the script | | Opt-out training clauses | Trains on work unless the person finds a setting | Never trained on; anything sent out is opt-in, named and per project | **Why the margin mark.** It is the film industry's own sign for *changed, look here*, so writers already read it. It prints, so a marked line on paper is still marked. It is flat, so it does not compete with the words. It disappears the moment the person makes the words theirs. And it makes no claim about quality: it says only *this came from somewhere else*. ## Components for machine help Use the [revision mark](https://kwark.space/designSystem/components/revision-mark.md) for proposed words, and the [AI assistance pattern](https://kwark.space/designSystem/patterns/ai-assistance.md) for the flow. The design system is adding components for the rest of the journey: a suggestion panel, a provenance label, a consent prompt, a prompt input, an agent plan, agent activity with Stop, and a review of an AI result. Until they are published, build those moments from the revision mark, Menu, Dialog and Toast with the rules on this page. **Do:** Offer *Zippo* under *The script mentions*, with the reason and *Add* or *Not needed*. Nothing is added until the writer says so. **Don't:** Add 14 props to the breakdown automatically and show *AI found 14 props* with a sparkle. **Do:** Mark a proposed scene heading with the margin star and *Suggested · from your outline*; the mark goes when the writer edits it. **Don't:** A glowing purple box around machine text that stays labelled *AI-written* after the writer rewrites it. **Do:** Export a storyboard pack for the tool the writer chooses, and bring the images back onto the panels. **Don't:** Generate boards inside Kwark from the script, on Kwark's servers, without asking. > **For agents:** - **Never** score, grade, rate, critique, rank or rewrite a person's writing, or show a quality percentage. > - **Never** save machine-proposed words or items into the work without a person accepting each one. > - **Never** use sparkles, glows, gradients or *AI* badges to mark machine help. > - **Never** send a person's work to an outside service unless they turned that on, for that project, knowing what is sent and to whom. > - **Must** mark proposed words with a revision mark and a label naming the source, until a person accepts or edits them. > - **Must** give every suggestion a reason in a plain sentence and a way to say no that sticks. > - **Must** make every machine action undoable in one step. > - **Always** say plainly what runs in Kwark today; never claim a model, a feature or a protection that does not exist. ## AI readiness test **Task:** Design how Kwark offers locations for the Locations list from the screenplay of Blank Pages. **Give the agent:** This page, the revision mark, the breakdown's "The script mentions", decisions 0002, 0004 and 0005. **Constraint:** Runs on the device; nothing is added until the writer agrees; no judgement of the script. **A reliable answer:** - Each location offered with the scene heading it came from and a plain reason - Add and Not needed per item, dismissals remembered - No Accept all into the work, and a batch toast says each can be changed - No sparkles, glows, confidence scores or AI labels - Undo in one step - Nothing sent off the device --- # Colour > Colour in Kwark is a set of roles. Components ask for the page, the surface or the accent, and the theme, the room or the project decides what that is. Source: https://kwark.space/designSystem/foundations/color ## How colour works here Kwark has two colour layers, and they never mix. - **Brand palette.** Five colours for the brand itself: the website, the case study, marketing, this site. They never appear in the app's working surfaces. - **Product roles.** The colours the app is made of: page, surface, line, text, accent, status. Each is a token with a light and a dark value, and inside the screenplay editor each follows the writing room. A component never names a colour. It names a role: `background: var(--k-surface)`. That is what lets one component sit correctly in light, dark, Paper and Midnight without a single change. > **For agents:** Use `--k-*` role tokens only. Never write hex, rgb or hsl in a component. If no role fits, stop and ask; do not add a colour. ## Brand palette Palette No. 300. Ink is the ground; the four colours are accents, one per area, following a 60-30-10 balance: 60% ink or paper, 30% one accent, 10% a second. | Token | Name | Light | Dark | Use | |---|---|---|---|---| | `--k-brand-ink` | Ink | #1b221e | | The ground. Text on light, background on dark. | | `--k-brand-coral` | Coral | #f28b71 | | Calls to action on brand surfaces. Ink text on it, never white. | | `--k-brand-mango` | Mango | #fac374 | | Highlights, comment pins, warmth. | | `--k-brand-mint` | Mint | #badfcf | | Calm confirmation, selected states on dark. | | `--k-brand-aqua` | Aqua | #83cfd3 | | Links to the technical side: code, agents. | ## Product roles | Token | Name | Light | Dark | Use | |---|---|---|---|---| | `--k-bg` | Page | #f8fafc | #191919 | The page behind everything. | | `--k-surface` | Surface | #ffffff | #1a1a1a | Cards, panels, dialogs, inputs. | | `--k-raise` | Raised | #f1f5f9 | #252525 | Hover, selected rows, pressed segments. | | `--k-line` | Line | #e2e8f0 | rgba(255, 255, 255, .1) | Hairlines and borders. | | `--k-line-strong` | Strong line | var(--k-text-2) | var(--k-text-2) | Field borders, checkbox outlines (3:1 against the surface). | | `--k-text` | Text | #0f172a | #e3e3e3 | Body and titles. | | `--k-text-2` | Quiet text | #5b6779 | #9ca3af | Meta, captions, placeholders (4.5:1). | | `--k-accent` | Accent | #98633f | #98633f | Primary actions. A project's own colour replaces it. | | `--k-on-accent` | On accent | #ffffff | #ffffff | Text and icons that sit on the accent. | | `--k-focus` | Focus | #0f172a | #f4f4f5 | The focus ring. | ### The accent belongs to the project Kwark's own accent is a warm copper: `#98633f`, with a light partner `#e8b58b` (`NEUTRAL_PROJECT_ACCENT` and `NEUTRAL_PROJECT_HIGHLIGHT` in `utils/colorUtils.ts`). It used to be a hard blue, so every project that had never chosen a colour read as blue; it is copper now so that an unchosen project reads in the app's own palette. When a writer gives a project a colour, the accent becomes that colour everywhere in the project: primary buttons, the caret, the scene headings on the page, the timeline's current-scene ring. The writer picks from ten presets (`PRESET_COLORS` in `shared/constants.ts`: Red, Orange, Amber, Lime, Emerald, Teal, Cyan, Blue, Violet, Pink), and each preset is a pair: | Part | App variable | Role here | What sits on it | |---|---|---|---| | The accent, strong | `--color-action` | `--k-accent` | `--story-on-accent`: black or white, whichever reads | | The accent, light | `--color-highlight`, `--project-accent` | `--k-accent-soft` | `--project-accent-text`, which the app's `--k-on-accent` points at | How it is applied (`utils/projectAccent.ts`): - **Before the first paint.** The accent is set on `` synchronously, and kept in `localStorage` (`thea_last_accent`), so a reload sets it in the document head before anything is drawn. An earlier version applied it after React had drawn, and every navigation flashed copper for a frame. - **Always with its text colour.** Every accent is set together with the colour that reads on it. Setting one without the other is what once left labels white on a pale accent. - **A colour nobody chose is no colour.** Three old default blues (`#1e40af`, `#3b82f6`, `#2d7ff9`) that older versions wrote into project records are treated as unset (`chosenAccent`). - **Dialogs can carry a project's colour.** `Modal` takes `accentColor` and `accentLight` and sets the pair on its own overlay, so a project's dialog opened from Home wears that project's colour. The text colour on an accent is chosen by brightness (the YIQ formula, black at 128 and above). That is fast but not a contrast check: on the Blue preset (`#3d7fea`) it picks white, which is 3.87:1, below 4.5:1 for body text. Until the rule is a real contrast calculation, put only 16px 600 or larger text on a strong accent, and test every preset. **This is why components never assume the accent is copper.** Test with a pale accent (Amber, Lime) and a dark one (Violet), in light and dark. ## Status Four pairs, each a strong colour for text and icons and a soft one for backgrounds. They are muted on purpose: Kwark tells people about problems without alarming them. | Token | Name | Light | Dark | Use | |---|---|---|---|---| | `--k-ok` | Ok | #2c6e49 | #6cc08a | Settled: Saved, Locked, Issued. | | `--k-info` | Info | #255799 | #7db4f0 | Worth knowing: Shared, Revised. | | `--k-warn` | Warn | #8a5a00 | #d8a44a | Needs attention soon: Out of sync, Clash in two days. | | `--k-danger` | Danger | #b4382c | #e0685c | Blocks work or destroys it: Delete, Clash today. | | `--k-rev` | Revision | #346a58 | #9fd4bf | Words a machine proposed. See AI and authorship. | **Do:** *Out of sync* in a warn badge with words. The colour supports the word. **Don't:** A red dot with no label, or red for a scene that is merely long. ## Light, dark and the rooms The app follows the system theme unless the person chooses. Add `class="dark"` (or `data-theme="dark"`) on ``. Inside the screenplay editor the writer chooses a room, and the roles take the room's values. See [Writing rooms](https://kwark.space/designSystem/foundations/rooms.md). ```html Revised ``` ## Colour in light rooms: pastels, a shade deeper Data colours (timeline marks, index-card lenses, avatars) are pastels taken about 20% darker in lightness, with hue and saturation kept. Never mix toward black: it reads as dirty. Never use plain pastels on white: they wash out. Keep dark ink on the fills and check the contrast. **Do:** Sage for dialogue and clean sand for action on the timeline, each a step deeper than a pastel, dark ink on top. **Don't:** Saturated blue blocks with white numbers, grey chips with an accent underline, or a sand that drifts to brown. ## Where this site and the app differ `kwark.css` takes its values from the app's `styles/tokens.css`. Four roles differ, each on purpose or because the two names mean different things: | Role | App | Here | Why | |---|---|---|---| | `--k-danger`, light | #e0685c in both modes, 3.33:1 on white | #b4382c, 5.93:1 | The app's light danger fails as text; dark keeps #e0685c | | `--k-on-accent` | #17110c: the text for the light accent (`--project-accent-text`) | #ffffff: the text for `--k-accent` (`--story-on-accent`), 5.01:1 on #98633f | The app's name pairs with `--k-accent-soft`; here it pairs with `--k-accent`, which is what a primary button needs | | `--k-line-strong` | #cbd5e1 light, #48433d dark | `var(--k-text-2)` | Field borders and checkbox outlines must reach 3:1 against the surface; #cbd5e1 on white is about 1.5:1 | | `--k-rev`, `--k-rev-bg`, `--k-rev-line` | Not defined | Defined | The revision mark for machine-proposed words is designed here first ([AI and authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md)) | **The accent in dark mode.** `--k-accent` stays #98633f in dark, in the app and here. On the #191919 page it is 3.51:1: fine as a button fill with white text on it, not enough for accent-coloured text or a thin icon. On dark, accent text and icons use `--k-accent-soft` (#e8b58b, 9.56:1), as the app's own dark screens do through `--project-accent`. ## Contrast | What | Minimum | Kwark target | |---|---|---| | Body text | 4.5:1 | 7:1 where it is the work itself (the script) | | Large text (24px, or 19px bold) | 3:1 | 4.5:1 | | Icons, field borders, focus ring | 3:1 | 3:1 | | Disabled controls | none | still readable; say why it is disabled | Check any pair here: ## No glow Kwark does not use glows, light washes, blurred colour blobs or gradient fills in its interface. They read as decoration, cost contrast, and make the interface louder than the work. Depth comes from a line and a step in tone. See [Elevation](https://kwark.space/designSystem/foundations/elevation.md). ## AI readiness test **Task:** Restyle a settings panel so it works in the Paper room and in dark mode. **Give the agent:** This page, Writing rooms, tokens.json. **Constraint:** No new colours. Say which roles you used. **A reliable answer:** - Only --k-* roles - No hex values - Text 4.5:1 in both - Accent never assumed to be copper --- # Content > Kwark's voice and tone: calm, plain and film-literate. How Kwark talks about saving and errors, the film words it uses and how, capitalisation, numbers, dates and times for crews, and names and roles. Source: https://kwark.space/designSystem/foundations/content ## The voice Kwark sounds like a calm, experienced colleague in the production office: someone who knows the craft, says what is true in as few words as it takes, and never makes you feel stupid or watched. The test, from principle 9 (*Honest and quiet*): **would we say this out loud to a nervous writer?** If a sentence would sound odd spoken across a table, it is wrong on screen. | Kwark is | So it | And never | |---|---|---| | Calm | States the state first, then what to do | Alarms, shouts, uses red for anything that does not block work | | Plain | Uses short, common words and full sentences | Uses jargon, internal names or library text | | Honest | Says only what is true, including *on this device* when the cloud is not involved | Claims something is saved, synced, sent or safe when it is not | | Film-literate | Uses the industry's words, correctly | Invents cute names for things crews already have names for | | Respectful | Treats every person as a filmmaker | Coaches, praises, jokes or judges the writing | | Private | Talks to the person alone | Compares them with anyone, or tells others what they did | > Kwark's people include students from 13 and producers with twenty films. Write for both at once: a bright 14-year-old and a working line producer should each read the sentence as written for them. Short, correct and kind does that. Slang, jokes and simplifications do not. ## Tone changes with the moment The voice stays the same. The tone follows what the person is doing. | Moment | Tone | Kwark says | |---|---|---| | Writing | Silent. The page is the only thing talking | Nothing, unless asked | | Pressing ⌘S out of habit | Reassuring, one line | *Saved. Your script saves as you write.* (Decision 0014) | | Waiting for the network | Matter of fact | *Safe here, waiting to reach the cloud* | | Something could not be stored | Steady, specific, one action | *This change has not saved yet, so the page stays open. A copy is kept on this device.* | | Letting someone in | Warm, plain | *Mira is in, as Co-writer.* | | Production paperwork | Exact, crew-ready | *Rev 2 issued. Save it as PDF to send it to the crew.* | | Removing something | Clear about what goes and what stays | *Scene moved to trash.* with Undo | | No access | Neutral, never accusing | *You do not have access to this. Your work is safe; ask the project owner if you need it.* | ## The voice of saving and sync Decision 0013 sets the order for every message about a person's work: **the state first**; then what happened; then that the work is safe, if it is true; then what to do. Never *failed*. | State | Words | Notes | |---|---|---| | Everything is up to date | *Safe* | The corner sync word | | Changes are waiting | *Safe here, waiting to reach the cloud* | Not an error. No red | | Offline by choice | *Safe on this device (offline by choice)* | After *Work offline* | | Local write succeeded | *Saved on this device* | Makes no cloud claim (Decision 0013, 4 November) | | In progress | *Saving…* | One ellipsis character | | A write did not land | *Not saved yet*, with *Retry saving* | The page stays open; Back waits | | Read-only because nothing is loaded | *The screenplay has not finished loading on this device.* | Never let a half-loaded script save | Every error from Firebase passes through `friendlyError()`, which turns codes into one calm sentence and replaces anything it does not recognise with *Something went wrong. Your work is safe; please try again.* Raw library text never reaches a person. > **For agents:** - **Must** say the state before the problem, and say *safe* only when the work really is safe. > - **Must** say *on this device* when nothing has reached the cloud. > - **Never** show the words *failed*, *error occurred*, *sync error*, *Firebase* or a code to a person. ## Film words, used correctly Kwark's people work in film; its words should be the words on a real set. Use the industry term where one exists, and use it exactly. Where the screen label is plainer than the trade word, the table says so. | Term | Means | In Kwark | |---|---|---| | Scene heading (slugline) | The line that opens a scene: *INT. EDIT SUITE – NIGHT* | Labelled *Scene heading* in the element menu; "slugline" is fine in help and docs | | Action | What we see and hear | *Action* | | Character cue (cue) | The speaker's name above dialogue | *Character* in the element menu; *cue* in docs | | Parenthetical | Direction in brackets under a cue | *Parenthetical* | | Transition | *CUT TO:*, *DISSOLVE TO:* | *Transition* | | Dual dialogue | Two characters speaking at once, side by side | *Dual dialogue* (⌘⇧D) | | Act, sequence, beat | Structure, from largest to smallest | Optional (Decision 0003). Never "plot point" scoring | | Eighths | Page length in eighths of a page, the way schedules count | *1 4/8* pages | | Breakdown | Tagging what each scene needs: props, wardrobe, vehicles | *Breakdown*; suggestions under *The script mentions* | | Stripboard, strip | The schedule as coloured strips, one per scene | Strips coloured by INT/EXT and DAY/NIGHT | | Shooting day | A day of the shoot | *Shoot day 3*; *Shooting days* on the planner | | Call sheet | The day's sheet for cast and crew | Issued as numbered revisions (Decision 0020) | | Call time, crew call | When people must arrive | *Crew call*, per person *call* | | Wrap | End of the day's shoot | *Wrap* | | Recce | Visiting a location before the shoot | *Recce*, a calendar category (Decision 0043) | | Table read | Reading the script aloud with the cast | *Table read* | | Dailies | The day's footage; in Kwark, the private record of a person's work days | *Dailies* (Decision 0043) | | Top sheet | A budget's one-page summary | *Top sheet* | | Revision | A changed, reissued version | *Rev 2*; *Changed since Rev 2* | Two Kwark names to keep exactly: - **Write** and **Prepare to shoot**, the two halves of a project (Decision 0009). *Understanding* is a code name only; never show it. - **Room**, for the editor's look (Decision 0015). Not *theme*, *skin* or *mode*. **Words that mean judgement in film are not Kwark words.** *Coverage*, *notes* in the sense of a reader's verdict, *pass*, *consider* and *recommend* describe someone grading a script. Kwark never does that (Decision 0002), so its interface never uses them about the writer's work. *Coverage* in the camera sense (the shots that cover a scene) is fine in the shot list. ## Capitalisation - **Sentence case everywhere** in the interface: buttons, titles, menus, labels, tabs. *Prepare to shoot*, not *Prepare To Shoot*. - **Screenplay elements are capitalised by convention** and only on the page: scene headings, cues, transitions, and a new element introduced in action (*he flicks a chipped ZIPPO*). The interface never borrows this. - **No all-caps labels** in the interface, and no small-caps eyebrows. - **Proper nouns**: Kwark, Bekwarky, Blank Pages (the demo project), Final Draft, Highland. - **Role names** are capitalised when they are the role in the sharing panel (*Reader*, *Actor*, *Co-writer*, *Director*, *Producer*, *Camera*, *Crew*, *Custom*) and lower case in a sentence about the job (*ask the director*). - **Keys** as the keyboard shows them: ⌘S on a Mac, Ctrl+S elsewhere; Esc, Tab, Enter. ## Numbers - **Numerals for every count**: *3 scenes*, *12 shots*, *1 character*. Spell out nothing for the sake of style. - **Scene numbers as written**: *Scene 12*, *Scene 12A*. Never *Scene #12* or *Sc. twelve*. - **Revisions**: *Rev 2*, never *Revision #2* or *v2*. - **Page length in eighths**: *1 4/8 pages*. - **Runtime as a person says it**: *about 1 h 42 min*, *2 min 40 sec*; on the timeline, a clock: *2:40*. Always *about* for an estimate. - **Percentages only for measures**: *Talk 62%*. Never a percentage of how "good" or "done" something is. - **Money as its own people write it**: *₹12,50,000* in India (lakh grouping), *$125,000* in the US. Show the currency symbol; budgets default to rupees and offer eight currencies. - **Plurals by count**: *1 row*, *2 rows*. Never *row(s)*. ## Dates and times for crews A call sheet is read at 5am by someone who has just woken up. Times and dates must be impossible to misread. - **Always the weekday with the date** on anything a crew acts on: *Tue 18 Nov*. The weekday catches the wrong-date mistake. - **Never all-numeric dates** in the interface (*11/12* is November or December depending on the reader). - **Times as the device shows them** (24-hour or 12-hour by the person's locale), with *am* and *pm* when 12-hour. The calendar's examples use 24-hour (*19:30–21:00*), which is the default on Indian and European sets. - **Name the time zone** when the shoot is somewhere else from the person reading. - **Days of the shoot**: *Shoot day 3*. When the schedule knows the total, say it: *Shoot day 3 of 18*. - **Relative words only when they cannot be misread**: *today* and *tomorrow* in a toast are fine; *next Tuesday* on a call sheet is not. - **Sunrise and sunset** on a call sheet are times for that location and date, labelled *Sunrise* and *Sunset*. ## Names and roles - **The character, not the actor.** In Write, *Mira* is the character. The actor who plays her is named in casting and on the call sheet. Never mix the two in one label. - **People's names as they give them.** Do not split names into first and last, do not assume a family name, and do not abbreviate. Some people have one name. - **Display name and legal name** are separate where the paperwork needs a legal name (contracts, crew lists). Show the display name everywhere else. - **Never assume gender.** Write *they* when you do not know, or use the name again. - **Name people only where it was chosen.** Whether someone's name appears on the project page is set per person in the sharing panel (Decision 0042); never add names to a surface that did not ask. - **Roles are about access, not identity.** *Reader* is what someone can do in this project, not who they are. ## Writing for every reader - **Short sentences.** One idea each. A second-language reader and a tired reader both thank you. - **Full forms in errors.** *Could not* and *do not* read more calmly than *couldn't* and *don't*, and translate more safely. Contractions are fine in friendly, low-stakes lines. - **No idioms or metaphors** a translator or a 13-year-old would trip on. - **No exclamation marks.** Calm has none. - **No emoji** in the interface. - **British or American spelling**: the app's strings are mixed today (*colour* in Kwark's own words, *Localised* in Settings). Keep one spelling within a screen, and match the screen you are editing. **Do:** *We could not reach the cloud just now. Your work is safe on this device and will go up when we can.* **Don't:** *Cloud sync failed (unavailable). Please try again!* **Do:** *Crew call 06:30, Tue 18 Nov. Shoot day 3.* **Don't:** *Call: 6:30 on 11/18 (Day 3)* **Do:** *Talk 62% · Action 38%*, nothing more. **Don't:** *62% dialogue: a little talky for a thriller.* > **For agents:** - **Must** write in sentence case, short sentences, no exclamation marks and no emoji. > - **Must** use the film terms in the table above exactly, and *Write*, *Prepare to shoot* and *Room* as Kwark's names. > - **Must** put the weekday with any date a crew acts on, and never write an all-numeric date. > - **Must** keep the character's name and the actor's name apart. > - **Never** use judgement words (*coverage* of a script, *pass*, *weak*, *strong*, *good*, *score*) about a person's writing. > - **Never** praise, coach or joke. ## AI readiness test **Task:** Write the messages for issuing a revised call sheet for Shoot day 3 of Blank Pages after the crew call moves from 06:30 to 07:00. **Give the agent:** This page, UX writing, decision 0020, the Toast component. **Constraint:** The crew may read it on a phone at 5am; Kwark sends no email. **A reliable answer:** - Names the revision (Rev 3) and what changed (crew call 07:00) with weekday and date - Tells the person how to send it (Save it as PDF) without claiming Kwark sent anything - Sentence case, no exclamation marks, no blame - Uses Shoot day 3 and Crew call exactly --- # Data visualisation > The charts Kwark draws (the timeline, the story spine, the stripboard, the calendar, Dailies, the budget's top sheet), the colours they use and in what order, labels over legends, accessible alternatives, and the one chart Kwark never draws: a score for the writing. Source: https://kwark.space/designSystem/foundations/data-visualization ## What Kwark charts, and why A chart in Kwark exists for one reason: to let a filmmaker **see** their own work or their own production so they can decide something. Indie shoots are short, so every scene shows its estimated runtime and the timeline shows talk against action. A crew needs to know which day is which, so the stripboard is coloured the way stripboards have always been coloured. Every chart answers principle 6: **does it measure the work, or evaluate it?** Only the first is allowed. A chart shows quantities and positions. It never shows a verdict, a target zone that turns green, or a comparison with other writers. | Chart | Where | What it shows | Component | |---|---|---|---| | Timeline | Under the screenplay; phone strip and sideways bay (Decision 0007) | Each scene's estimated length, coloured by talk or action; acts; targets; the current scene | [Script timeline](https://kwark.space/designSystem/components/script-timeline.md) | | Talk and action | Timeline card | One stacked bar: share of screen time that is dialogue against action | Part of the timeline | | By act | Timeline card | A row per act: its length and share of the whole | Part of the timeline | | Story spine | Outline, structure view (Decision 0031) | One band per section at its planned share, a segment per part, a dot per beat | [Outline board](https://kwark.space/designSystem/components/outline-board.md) | | Stripboard | Schedule | One strip per scene, coloured INT/EXT and DAY/NIGHT | [Stripboard strip](https://kwark.space/designSystem/components/stripboard-strip.md) | | Day planner | Schedule | A day from crew call to wrap, as blocks | [Production timeline](https://kwark.space/designSystem/components/production-timeline.md) | | Calendar | Project calendar (Decision 0043) | Seven categories of work across days and hours | [Production calendar](https://kwark.space/designSystem/components/production-calendar.md) | | Dailies | A person's own record (Decision 0043, Dailies) | Week film strips with up to three quiet bands per day; a year contact sheet | [Dailies frame](https://kwark.space/designSystem/components/dailies-frame.md) | | Budget | Budget's top sheet | Sections, contingency, tax and total, as a table | [Budget top sheet](https://kwark.space/designSystem/components/budget-top-sheet.md) | Generic charts for anything else (a bar, line, area, donut, heatmap or sparkline) are in the components: [bar chart](https://kwark.space/designSystem/components/bar-chart.md), [line chart](https://kwark.space/designSystem/components/line-chart.md), [area chart](https://kwark.space/designSystem/components/area-chart.md), [donut chart](https://kwark.space/designSystem/components/donut-chart.md), [heatmap](https://kwark.space/designSystem/components/heatmap.md), [sparkline](https://kwark.space/designSystem/components/sparkline.md), [data table](https://kwark.space/designSystem/components/data-table.md), [Gantt chart](https://kwark.space/designSystem/components/gantt-chart.md). They follow every rule on this page. ## The timeline, in detail The specimen above is the desktop timeline. Its rules are the model for every chart in Kwark: - **One reading, in words, first.** *Runs about 1 h 42 min*. The chart illustrates the sentence; it does not replace it. - **Every mark means one thing.** A block is a scene; its width is its estimated screen time; its colour is what fills it (mostly dialogue, mostly action, or both, drawn half and half). A scene too narrow to label still keeps its number for screen readers. - **The current scene** is a 2px ring in the project's colour with a pointer above it. No glow, brightness filter or particles (Decision 0041). - **Targets** are dashed lines the writer set, labelled with their own words (*Act 2 break · aim 55 min*). They are the writer's aims, not Kwark's. - **The ruler** marks minutes often enough to read and never crowded: every 1, 2, 5, 10, 15, 30 or 60 minutes, whichever gives twelve or fewer marks. - **Talk and action** is a measure. *Talk 62% · Action 38%*, headed *in screen time, headings and transitions left out*. There is no "good" range, no colour for too much talk, no genre norm. - **The colours follow the room.** Talk and action come from the room's pair (see [Writing rooms](https://kwark.space/designSystem/foundations/rooms.md#timeline-marks)), and each block's fill is pulled toward the page until its number reads. On a phone the timeline rests as a 22px strip under the menu: slide a thumb to scrub, with a loupe that names the scene (*Scene 12. INT. EDIT SUITE – NIGHT · 26:40 of 102:00 · 2:40 long*: the clock counts minutes and seconds); tap to open; turn the phone sideways for the full bay (Decision 0007). ## The story spine Above the outline's rows, the story spine shows the story at a glance (Decision 0031). Writers never see the word *spine*: the strip is announced as *The story at a glance*. ```html

3 acts · 23 beats

``` - **Band**: a section, as long as the share the writer gave it in its title (*Act 1 (25%)*, or a range such as *(0–10%)* read as its width), or evenly split if they gave none. - **Segment**: a part inside the section. - **Dot**: one beat. Up to 12 per segment, then *+n*. - **Total line**: sections and beats. - Choosing a section scrolls to it. On a phone the strip scrolls sideways. Its remove condition is written down: writers ignore it in testing, *or read the band length as a judgement*. That is the line every chart in Kwark walks. ## Colour order for series For charts with up to four series, use the chart tokens `--k-chart-coral`, `--k-chart-mango`, `--k-chart-mint` and `--k-chart-aqua`: Palette No. 300 deepened in light mode so every mark reaches 3:1 on white, and the brand colours as they are in dark. For five or more categories, or when a chart shows calendar categories, use the calendar colours below. Kwark's data colours are muted, warm and named. Use them in this order for categorical series. The order is the calendar's (Decision 0043), because those seven are already tested together in light and dark and each has a fill, a stripe and an ink. | Token | Name | Light | Dark | Use | |---|---|---|---|---| | `--k-cal-writing` | 1 · Writing (copper) | #98633f | #e8b58b | First series. Writing sessions | | `--k-cal-rehearsal` | 2 · Rehearsal (sage) | #4f7359 | #86b392 | Second series | | `--k-cal-reading` | 3 · Reading (ochre) | #a87b32 | #dcb36a | Third series. Stripe is 3.3:1 on its fill: never text | | `--k-cal-shoot` | 4 · Shoot (olive gold) | #826d35 | #c4b068 | Fourth series. Shoot days | | `--k-cal-recce` | 5 · Recce (slate blue) | #4d6a7a | #83aac0 | Fifth series | | `--k-cal-meeting` | 6 · Meeting (mauve) | #7c5c6b | #be97aa | Sixth series | | `--k-cal-deadline` | 7 · Deadline (brick) | #a44a3f | #df8275 | Last, and only for deadlines or what blocks work | | `--k-cal-muted` | Muted | #78716c | #8c867d | Away, rest, phases, anything in the background | Each category has three tokens: `--k-cal-` (the stripe and the mark), `--k-cal--bg` (a soft fill) and `--k-cal--ink` (text on the fill). Measured in light mode, ink on fill is 6.8:1 to 8.9:1 and the stripe on its fill is 3.3:1 to 4.9:1; in dark mode, ink on fill is 8.6:1 to 10.4:1. The day-job hours use `--k-cal-dayjob-bg` and `--k-cal-dayjob-stripe`, a faint hatch, never a colour that says *wasted time*. Rules for series colour: - **Two series**: talk and action inside the editor use the room's pair. Outside it, use copper and sage. - **More than seven series** is the wrong chart. Group, or use a table. - **Brick is never a series colour by default.** It means *deadline* or *blocks work*, as status red does. - **One series in a chart?** Use `--k-text` at full strength for the mark and `--k-text-2` for axes. Colour only when there is more than one thing to tell apart. - **Status colours** (`--k-ok`, `--k-warn`, `--k-danger`) are for state, never for series. - **Never** a rainbow scale, a saturated palette, or colours mixed toward black. ### Dailies: the three kinds of work Dailies frames show up to three quiet bands a day, never volume and never streaks. | Token | Name | Light | Dark | Use | |---|---|---|---|---| | `--k-kind-story` | Story | #a8734c | #e8b58b | Writing, outline, characters, research | | `--k-kind-prep` | Prep | #627d5c | #a9bfa3 | Breakdown, shots, schedule, departments | | `--k-kind-performance` | Performance | #5f7393 | #a9b8cf | An actor marking a scene Read, Rehearsed or Off book | In light mode the three measure 4.0:1, 4.6:1 and 4.8:1 against white, so they are bands, not text. Dark mode lifts them (`#e8b58b`, `#a9bfa3`, `#a9b8cf`), each above 8:1 on the dark surface. ### The stripboard: an old code, kept The stripboard uses the four paper colours production offices have used for decades, kept exactly so a crew reads it at a glance: | Strip | Colour | Ink `#1f2427` on it | |---|---|---| | INT. DAY | Off-white `#f5f4ee` | 14.2:1 | | EXT. DAY | Yellow `#f1d563` | 10.8:1 | | INT. NIGHT | Blue `#8fb4d6` | 7.2:1 | | EXT. NIGHT | Green `#93c197` | 7.7:1 | These are one of the three places hex values are allowed outside the token file (`docs/design-system.md`), because they are the industry's, not Kwark's. Every strip also says *INT.* or *EXT.* and *DAY* or *NIGHT* in words. ## Light rooms: pastels a shade deeper In light themes, data marks (the timeline, index-card lenses, avatars) are pastels taken about 20% darker in lightness, with hue and saturation kept. The timeline pairs a clay or sage for talk with a clean sand for action, and the sand must stay sand, never drifting into tan. Rejected, and not to be revived: - plain pastels, which wash out on white; - solid saturated blue with white numbers; - any colour mixed toward black, which reads as dirty; - grey chips with an accent underline, which were hard to understand. Lower the lightness in oklch or HSL; never mix with black. Keep dark ink on the fills and check the contrast: Daylight's clay carries 8.0:1, its sand 11.5:1. ## Labels over legends - **Label the thing directly.** Act names sit on the acts; scene numbers sit on the scenes; the budget's sections carry their totals. A legend is the last resort, for marks too small to label. - **When a legend is needed**, it uses the same words as the interface (*Mostly dialogue*, *Mostly action*, *Dialogue and action*) and sits under the chart, in reading order. - **Numbers carry units** (*24 min*, *₹12,50,000*, *1 4/8 pages*) and use tabular figures (`font-variant-numeric: tabular-nums`) so columns line up. - **Estimates say so**: *about*. - **Axis text** is `--k-text-2` at `--k-fs-meta`; gridlines are `--k-line`. Nothing smaller than 11px, and 12px on a phone. - **Bars start at zero.** No dual axes, no truncated scales, no 3D, no pie with more than five slices. - **Motion is not information.** Bars may grow in on first draw (and not at all under reduced motion); nothing pulses. ## Accessible charts Every chart has a text alternative that carries the same numbers. | Chart | Alternative | |---|---| | Talk and action bar | `role="img"` named *Talk 62 percent, action 38 percent*, and the labels beside it in text | | Timeline strip (phone) | A slider named *Runs about 1 h 42 min*, value text *Scene 12, INT. EDIT SUITE – NIGHT, at 26:40* | | Timeline scenes (desktop) | Each scene a button named with its number, heading and length | | Story spine | Each section a button with its name and beat count; the total line in text | | Budget | It is already a table | | Calendar | Agenda view is the list alternative, and the default on phones | | Any new chart | A *Show as table* control, or a table beside it, with the same rows | - **Never colour alone.** Strips say INT/EXT and DAY/NIGHT in words; balanced scenes are split, not a third colour; a clash in the calendar carries an icon, and its name says *clash*. - **Interactive marks are buttons** with names, reachable by keyboard, with the focus ring drawn inside the mark so it is not clipped. - **Patterns are allowed** where two colours sit side by side (the day-job hatch) and help people who cannot tell the colours apart. ## Charts Kwark never draws - **No scores for writing**: no pacing score, readability grade, dialogue quality, "engagement" or sentiment arc of the script. - **No targets that judge**: no green zone for runtime, no red bar for a long scene, no genre benchmark for talk against action. - **No counts of the person**: no word-count streaks, no heatmap of writing days, no leaderboard, no "most productive hour" (Decisions 0001, 0008, 0036). Dailies shows kinds of work, never volume. - **No percentages of done** for creative work. *Conviction %* in the idea module is a recorded deviation to remove (Decision 0002). - **No comparison with other writers or projects.** The older *Dialogue analytics* panel in the screenplay (DialogueAnalytics.tsx) uses eight saturated hex colours from a chart library and all-caps labels. It does not follow this page and should move to these rules when it is next touched. **Do:** *Runs about 1 h 42 min*, scenes labelled with their numbers, talk and action in the room's pair, a table or named buttons for screen readers. **Don't:** A runtime gauge that turns red past 110 minutes, a legend of eight saturated colours, and no text alternative. **Do:** The story spine's bands at the shares the writer typed, with a dot per beat and the counts in words. **Don't:** A "structure health" ring showing 72% with a tip to add beats to Act 2. **Do:** Clay and sand a shade deeper than pastel, dark ink on top, checked at 4.5:1. **Don't:** Plain pastels on white, or a sand mixed toward black until it turns brown. > **For agents:** - **Must** state the chart's main reading in words before or above the chart. > - **Must** use `--k-cal-*` in calendar order for categorical series, the room's pair for talk and action, and `--k-kind-*` for Dailies. > - **Must** label marks directly; use a legend only for marks too small to label, in the interface's own words. > - **Must** give every chart a text alternative with the same numbers, and never rely on colour alone. > - **Must** start bars at zero, carry units, and say *about* for estimates. > - **Never** chart a score, grade, target zone or comparison of a person's writing or a person's activity. > - **Never** use status colours, saturated palettes or colours mixed toward black for series. ## AI readiness test **Task:** Add a chart to the Schedule that shows how many shoot days each location needs for Blank Pages. **Give the agent:** This page, the bar chart and data table components, decision 0043, Colour. **Constraint:** Works in light and dark, on a phone, and for a screen reader; no judgement. **A reliable answer:** - A one-line reading in words (for example "6 locations over 18 shoot days") - Horizontal bars from zero, each labelled with the location and its days - One series in --k-text, or --k-cal-shoot if it sits with other categories - A data table alternative with the same rows - No targets, red bars or rankings --- # Elevation > Kwark is flat. Depth is a line and a step in tone; a shadow is only for something that floats above the page, and the layers it floats on are numbered once. Source: https://kwark.space/designSystem/foundations/elevation ## Flat, by rule Kwark's surfaces do not glow, blur, lift on hover or cast light. On 15 November 2026 the founder saw a soft accent glow in the corner of a dialog and said to remove that lighting glow everywhere in the app; it was taken out of the `Modal` and four screens the same day. Three days earlier, Decision 0041 had removed the coloured light layers from the screenplay editor's rooms and the glow, brightness filter and rising particles from the timeline's current scene. The reason is the same both times. A writer spends hours on one screen. Light effects compete with the words, cost contrast, and make the interface louder than the work. The tools Kwark's writers measure it against (Final Draft, Highland, Fade In) have flat desks. So depth in Kwark is made of two things only: - **A line.** `--k-line`, one pixel, where one surface meets another. - **A step in tone.** The page, then a surface on it, then a raised area on that surface. > **For agents:** Never add a glow, a coloured or blurred shadow, a radial wash, a backdrop blur used as decoration, or a gradient fill to app chrome. Never give a resting card, row or panel a shadow. Depth is `--k-line` plus a step from `--k-bg` to `--k-surface` to `--k-raise`. ## Three tones | Step | Token | Light | Dark | Is | |---|---|---|---|---| | Page | `--k-bg` | #f8fafc | #191919 | The page behind everything: the desk | | Surface | `--k-surface` | #ffffff | #1a1a1a | Cards, panels, dialogs, inputs, menus | | Raised | `--k-raise` | #f1f5f9 | #252525 | Hover, the selected row, the pressed segment | | Inset | `--k-inset` | #f1f5f9 | #141414 | Wells sunk into a surface: a code block, a drop zone | In light the surface is a clear step brighter than the page. In dark the steps are small (#191919, #1a1a1a, #252525), so a surface is set apart mostly by its line, and the raised tone carries hover and selection; a dark interface that brightens sharply toward the viewer reads as lit from the front. Inside the screenplay editor the three steps come from the room (desk, chrome, chrome hover), so the same order holds in Paper or Midnight. **Selection is a tone, not a lift.** A selected scene in the list takes `--k-raise`; it does not grow, cast a shadow or gain a border colour. ## What floats A thing floats when it sits above the page for a moment and goes away: you opened it, and you will close it. Only these carry a shadow. | Floats | Shadow in the app | Here | |---|---|---| | Dropdown and context menus | `0 16px 36px` at 55%, `0 2px 6px` at 20% (`DropdownMenu.css`) | `--k-shadow-pop` | | Dialogs on a desktop | The `Modal` panel has a border and sits on a backdrop of the page at 82% | `--k-shadow-pop` | | Toasts | A large soft shadow (`shadow-2xl`) | `--k-shadow-pop` | | The phone dial and its items | `0 6px 20px rgba(0,0,0,.35)` (`components/ui/system.css`) | `--k-shadow-pop` | | The timeline loupe while scrubbing | `0 12px 30px rgba(0,0,0,.35)` (`editor.css`) | `--k-shadow-pop` | | The editor's phone tools menu | `0 16px 48px` at 40% | `--k-shadow-pop` | `--k-shadow-pop` is `0 1px 2px rgba(15,23,42,.06), 0 12px 32px rgba(15,23,42,.12)` in light and `0 2px 6px rgba(0,0,0,.2), 0 16px 36px rgba(0,0,0,.55)` in dark (the dropdown menu's own shadow): a tight contact shadow and a soft ambient one, both neutral, never tinted with the accent. The app's floating things predate the token and each wrote its own; they converge on it as they are touched. **Bottom sheets do not need a shadow.** A sheet rises over a backdrop (`--overlay-backdrop`, the page dimmed), so the backdrop already separates it. The app's `.k-sheet` has a border and no shadow. ## The page on the desk One resting thing has a shadow: the screenplay page in the editor, on a desktop. It is paper lying on a desk, and the writer needs to see where the sheet ends. - `editorTheme.ts` works the shadow out from the room's desk colour, so it is never a grey smudge on a coloured desk. In light rooms: `0 1px 2px` and `0 18px 44px`, both the desk colour mixed 70% toward black at 10% and 14% opacity. In dark rooms: a 1px inner highlight at 3% white and `0 24px 60px rgba(0,0,0,.45)`. - The page also has a 1px edge (`--page-edge`): the paper colour mixed 9% toward black in light rooms and 7% toward white in dark ones. - On a phone the page is the screen: no edge, no shadow, no corner. This is not a glow. It falls downward, it is the colour of the desk in shade, and it exists because paper on a desk casts one. The production office's paper (`.po-paper`, the call sheet) also sits on its desk with a downward shadow (`0 30px 60px -30px #000, 0 2px 5px #0006`); it is not yet worked out from the desk colour as the screenplay page's is. ## Layers Things that float are stacked in a fixed order. Each layer has one number, and a component picks its layer; it never picks a number. | Layer | z-index | What sits there | |---|---|---| | The page | 5 | The screenplay page inside its scroll box | | Side panels | 20 | The scene list and the editor's panels | | Sticky header | 30 | `PageHeader` on a phone | | Timeline | 50 | The timeline band and the phone strip | | Editor menu bar | 100 | File, Edit, View, Tools, Help | | Timeline bay | 110 | The full-screen sideways edit bay, above the menu bar (Decision 0007) | | Dial | 320 | The phone's one floating button | | `--ds-z-base` / `--k-z-base` | 500 | Floating controls inside a screen (the focus-mode exit) | | `--ds-z-high` / `--k-z-high` | 1000 | Bottom sheets, toasts, combobox lists, the editor's own dialogs | | `--ds-z-critical` / `--k-z-critical` | 2000 | Reserved for what must cover everything the app draws | The app's `--ds-z-*` tokens live in `styles/tokens.css`; this site's `--k-z-*` tokens are the same numbers under the new names. ### The Modal's priority `components/ui/Modal.tsx` takes a `priority` prop: `'base' | 'high' | 'critical'`, default `'base'`. | Priority | Used for | z-index in the app today | |---|---|---| | `base` | Ordinary dialogs: Scene details, Import | 10000 | | `high` | A dialog that may open over another: Sign in, the project form, Create view | 50000 | | `critical` | Confirmations and locks that must win: `ConfirmDialog`, Unlock project | 99999 | These numbers are far above the `--ds-z-*` scale; the dropdown menu sits at 60000 and the full-screen loader at 9999. They work, but they are a second scale. The rule for new work is to choose a priority, never a number, so the scale can be brought back to 500 / 1000 / 2000 in one place. ```html
Blank PagesPage · surface · line
Scene 11
Scene 12 raised
Scene 13
inset: 12A · 1 3/8
Scene 12 moved to Act 2
``` Switch to Dark: the order holds. The header and the scene list are flat, separated from the page by a line and a tone. Only the menu and the toast, which you opened and will close, carry `--k-shadow-pop`. ## Do and don't **Do:** A selected scene row in `--k-raise` with no border change. A context menu with `--k-shadow-pop` over a flat list. A card that is separated from the page by a 1px `--k-line` and nothing else. **Don't:** Cards that lift and gain a shadow on hover. A coloured shadow in the project accent under the primary button. A blurred glass panel over the timeline. A dialog with a soft light in its corner. **Do:** A confirmation opened from the Share dialog uses `ConfirmDialog`, which is `priority="critical"`, so it appears above the dialog that opened it. **Don't:** A new dialog that sets `style={{ zIndex: 100001 }}` to win a fight with another dialog, so the next dialog needs 100002. ## Rules - **Must** choose a layer by name (`--k-z-base`, `--k-z-high`, `--k-z-critical`, or the Modal's `priority`). **Never** write a z-index above 2000 in new code. - **Must** use `--k-shadow-pop` for anything that floats, and nothing else for a shadow. - **Never** put a shadow on something at rest. The screenplay page on a desk is the one exception and is drawn by the room, not by a component. - **Always** pair a floating surface with a way out: Escape, a Close button, or a tap on the backdrop; and return focus to what opened it. - **Never** use `backdrop-filter: blur` as decoration. A backdrop is the page dimmed (`--k-backdrop`), not frosted. ## AI readiness test **Task:** Add a "Jump to scene" popover that opens from the editor's menu bar and lists scenes, with a search field at the top. **Give the agent:** This page, Radius, the layers table, the editor's menu bar markup. **Constraint:** It must sit above the timeline and the menu bar but below any confirmation dialog, in every room. **A reliable answer:** - Popover uses --k-surface, a 1px --k-line border, --k-radius-card and --k-shadow-pop - Its layer is above the menu bar (100) and below --k-z-high, chosen by token, not a five-digit number - Rows take --k-raise when selected, no lift - Escape closes it and focus returns to the menu bar button - No glow, blur or tinted shadow --- # Iconography > One icon pack, three sizes, one stroke, and a word beside almost every icon. Which glyph each Kwark module uses, which glyphs may stand alone, and what a chevron promises. Source: https://kwark.space/designSystem/foundations/iconography ## One pack Every icon in Kwark comes from Lucide, through `lucide-react` (`^0.562.0` in the app's `package.json`). One pack means one drawing hand: the same 24-unit grid, the same round joins, the same weight. Mixing packs is how an interface starts to look assembled rather than designed. - In the app, icons are drawn through the shared `Icon` component (`components/ui/Icon.tsx`), which fixes the size to one of three steps and the stroke to 1.75, and hides the icon from screen readers unless it is given a `label`. - `IconButton` and `TextButton` use `Icon` inside, so a button never sets its own icon size. - On this site and in framework-free work, paste Lucide's SVG markup as it ships (`viewBox="0 0 24 24"`, `stroke="currentColor"`, `fill="none"`), set the size with `--k-icon-*`, and add `aria-hidden="true"`. > **For agents:** Use lucide-react through `Icon`, `IconButton` or `TextButton`. Never import another icon pack. Never draw an inline `` for something Lucide has. Never set an icon to a size other than 14, 16 or 20. ## Three sizes | Size | Where | |---|---| | **14px** `--k-icon-sm`, `Icon size="sm"` | Beside 12px text: a chevron after a word (`TextButton` with `opens`), a tick in a menu, the breadcrumb's chevrons and ⋯, small inline actions in the editor (Note, Line note) | | **16px** `--k-icon-md`, `Icon size="md"` (default) | Beside 14px text: inside buttons and menu items, `IconButton` on a desk, list row leads | | **20px** `--k-icon-lg`, `Icon size="lg"` | Where the icon leads on its own: the phone header's back chevron, the phone dial, a dialog's Close | "13 and 15 are not steps" is written into `Icon.tsx`. A bigger icon is not a more important one; importance comes from position and the word beside it. Illustrations and empty-state art are not icons, and Kwark's empty states carry no illustration at all. The hit area is not the icon. A 16px icon sits in a 32px button on a desk and a 44px button under a thumb (`--k-tap`). ## Stroke and colour - **Stroke 1.75** at every size, through `Icon`. Lucide's own default is 2; older code that imports a Lucide icon directly still draws at 2, and a few places force 3 or 4 for emphasis. Do not copy those: emphasis comes from colour and position, never from a heavier line. - **Never** fill a Lucide outline icon, and never give it a second colour. - **`currentColor` always.** The icon takes the control's colour, so hover, disabled and focus need no icon rule of their own. Quiet icons (a menu item's lead, a row's trailing chevron, an idle `IconButton`) are `--k-text-2`; on hover an `IconButton` steps to `--k-text`. - **Never** colour an icon with the accent unless the whole control is the accent. A copper bin icon next to grey ones reads as a warning. ## Icons beside words A control says what it is with a word. The icon helps a person find the word again next time; it does not replace it. ```html ``` ## Glyphs that may stand alone Only glyphs that mean the same thing in every app may appear without a word, and only where space is short (a phone header, a row, a dialog's corner). Each still has an accessible name that says what it acts on. | Glyph | Lucide | Means | Accessible name, for example | |---|---|---|---| | | `ChevronLeft` | Back | Back to Outline | | | `X` | Close | Close dialog; Close Scene 12 details | | | `MoreHorizontal` | More | More actions for Scene 12 | | | `Plus` | Add | Add scene to Act 2 | | | `Search` | Search | Search scenes | | | `Check` | Selected (a tick in a menu, not a button) | Not a button; the menu item is announced as checked | - **Must** give every icon-only button a `label` (`IconButton` requires one) that names the action and its object: *More actions for Scene 12*, not *More*. `IconButton` also sets it as the `title`, so a pointer user sees it on hover. - **Never** rely on the tooltip as the name. Test with tooltips unavailable. - **Never** make an icon-only button for anything not in this table. A *Lock script* or *Issue call sheet* button always carries its word. - An icon beside a word is decorative: `aria-hidden="true"`, no label, so a screen reader does not say "file text Screenplay". ## What a chevron promises A chevron is a promise about what happens next, and Kwark keeps the promise the same everywhere. | Chevron | Promise | Where | |---|---|---| | Chevron down, 14px, after a word | This opens a menu or a list here | `TextButton` with `opens`, the phone header's **Menu**, the breadcrumb's switchers (Decision 0044) | | Chevron right, 14px, at the end of a row | This row opens another page of choices | `MenuSheet` rows that drill down. As the breadcrumb's separator on a desk it means *inside*: Blank Pages › Outline | | Chevron left, 20px, at the start of a header | Back to where you came from | `PageHeader` on a phone, `MenuSheet`'s back row | - **Never** put a chevron on a button that does something at once (Save, Delete, Export PDF). - **Never** use an arrow (`ArrowRight`) as a chevron. An arrow means something moves or is sent: *Move to Act 2*, a next step in a sequence. - Decision 0044 gives the phase switch (*Write* / *Prepare to shoot*) and the module switch the same chevron treatment, so a writer learns it once. ## The icons Kwark's modules use A module's icon is the same on the project board, in the breadcrumb's module switcher, in the production office's menu and on the phone. It is read from one place: `shared/board/boardTemplate.ts` (Write, and the board's built-in modules) and `pages/PreProduction/shared/productionModules.ts` and `departments.ts` (Prepare to shoot). ### Write ```html
Characters & Locations
World & Lore
Outline
Screenplay
Research
Idea & Themes
Pitch
``` ### Prepare to shoot ```html
Breakdown
Shots & Boards
Schedule & Call Sheets
Camera & Light
Art
Costume & Makeup
Sound & Music
Stunts & Effects
VFX
Locations
Cast & Crew
Calendar
Budget
Paperwork
Director’s Book
Look Book
``` | Module | Lucide icon | Module | Lucide icon | |---|---|---|---| | Characters & Locations | `Users` | World & Lore | `Globe` | | Outline | `Network` | Screenplay | `FileText` | | Research | `Microscope` | Idea & Themes | `Lightbulb` | | Pitch | `Presentation` | Breakdown | `Tag` | | Shots & Boards | `Table` | Schedule & Call Sheets | `Clapperboard` | | Camera & Light | `Video` | Art | `Hammer` | | Costume & Makeup | `Shirt` | Sound & Music | `Music` | | Stunts & Effects | `Flame` | VFX | `Sparkles` | | Locations | `MapPin` | Cast & Crew | `Users` | | Calendar | `CalendarDays` | Budget | `Wallet` | | Paperwork | `FileBadge2` | Director’s Book | `BookOpen` | | Look Book | `Palette` | | | Navigation around them: `Home` for Home in the breadcrumb (icon only, named *Home*), `LayoutGrid` for *Back to the project*, `SlidersHorizontal` for *Choose departments*, `Tv` for *Episodes* in a series, `Orbit` for a franchise. - **Must** take a module's icon from the module list, never choose one in a screen. - **Never** reuse a module's icon for something else. `Sparkles` is VFX in Kwark; it is never a badge for "AI" or "new", and Kwark has no sparkle decoration anywhere ([AI and authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md)). - `Users` currently stands for two modules, Characters & Locations and Cast & Crew. They sit in different phases, and each always carries its word, so this is tolerated, not a pattern. - An unknown module name gets `Tag`, a neutral mark, so a board saved by a newer copy of the app still draws (`boardIcon`). ## Custom SVG Kwark draws its own SVG only for things that are not icons and that Lucide cannot have: the timeline's scene blocks, the script overview's page thumbnails, lighting and blocking overheads, charts, the Kwark mark in the loader. In November 2026, 32 files under `pages`, `components` and `shared` contain an inline ``; most are these. An inline SVG that draws a chevron, a bin, a plus or a close is a bug. ## Right-to-left and direction A screenplay line in Urdu, Arabic, Persian or Hebrew runs right to left (Decision 0046), but Kwark's chrome stays in English and left to right. Directional chrome glyphs (back, the drill-down chevron) therefore do not mirror today. If the chrome is ever translated into a right-to-left language, back and forward chevrons mirror; play, rewind and timeline direction do not, because time runs the same way on every screen. ## Do and don't **Do:** A row for Scene 12 with a 16px `FileText` lead, the title, and a ⋯ `IconButton` named *More actions for Scene 12*. The phone header's back chevron at 20px, named *Back to Outline*. **Don't:** A toolbar of seven unlabelled icons (lock, eye, layers, zap, sliders, copy, bin) with tooltips as their only names, two of them from a different pack and one hand-drawn. **Do:** *Menu* with a 14px chevron down, because it opens a menu. *Export PDF* with no chevron, because it starts at once. **Don't:** *Save* with a chevron because it sits in a row of buttons that have them, or a chevron right on a row that opens a dialog instead of another page. ## AI readiness test **Task:** Add a "Dailies" entry to the Prepare to shoot module list, with its icon, and a ⋯ button on each day's row in the Dailies list. **Give the agent:** This page, productionModules.ts, departments.ts, the ListRow and IconButton components. **Constraint:** Use only Lucide. Do not reuse an icon another module already uses. **A reliable answer:** - One Lucide icon chosen that no other module uses, registered in the module list, not in the screen - Drawn through Icon at one of the three sizes (md in menus), stroke 1.75 - Every row's ⋯ is an IconButton with a label like More actions for Day 4 - No chevron on buttons that act at once - No inline SVG and no second icon pack --- # Inclusive design > Who Kwark is for, what each of them stands to lose, and how Kwark decides on their behalf: students from 13, cheap phones on slow networks, offline work, many languages, calm for every kind of mind, privacy and cost. Source: https://kwark.space/designSystem/foundations/inclusive-design ## Decide for real people, in their real situation Inclusive design at Kwark is not a list of edge cases. It is the main case. The people Kwark is built for include a 14-year-old writing a first short on a school laptop, a crew member reading a call sheet on a five-year-old Android phone in a field with one bar of signal, an actor whose lines are in Tamil, a writer who can only work after the day job ends, and someone who finds a flashing badge hard to ignore. Every decision that touches people runs through the same questions, taken from *How we decide*: | Question | Asked of a change | |---|---| | Who is affected? | Name them: the student, the actor, the crew, the owner. Not "users" | | What were they doing a minute ago? | Writing, travelling to set, on a break at work | | What are they afraid of right now? | Losing work, being judged, being seen, running out of data | | What do they lose if we do this? | Calm, privacy, time, data allowance, money, the ability to undo | | What do they lose if we do nothing? | The honest answer, written down | | What is the smallest thing that helps? | Build that first | | What can they not undo? | Design that part twice | > **The default rule.** Anything that nags, counts, notifies or watches is **off by default** and lives in Settings, where a person can find it and turn it on for themselves (Decision 0008). Anything that protects work or privacy is **on by default**. When in doubt about which side a feature falls on, it is the first kind. ## Students from 13 Kwark serves students aged 13 and above, including students under 18. That is confirmed, and an 18-and-over workaround is not the plan. Under-13 accounts are outside the first version. What this changes in design: - **Private by default, always.** No public profile, no student directory, no public counts. New collaborators join as Readers and the request link is off until the owner turns it on (Decision 0042). A student cannot become publicly findable by using Kwark. - **No social and no ranking.** Competitions, leaderboards and feeds belong on Bekwarky, not here (Decision 0001). Teenagers already live with enough comparison. - **Plain words, not childish ones.** Write for a bright 14-year-old and a working producer at the same time: short sentences, correct film words, no slang, no jokes. The same wording serves both. - **No teaching inside fields.** Structure, not coaching (Decision 0004). A student learns the call sheet by making one that a crew can use. - **Consent is designed, not assumed.** The launch plan requires age and country checks before sign-in, a guardian route where the law needs one, and a working account option for students whose school blocks Google sign-in. That work is planned and gated; it is not built yet. Never design a screen that assumes it exists. > **For agents:** - **Never** design a public surface, a directory or a "share to everyone" default that a student account could reach. > - **Never** add profiling, targeted promotion or session replay. > - **Must** treat cast and crew contacts, photos and child actors' details as sensitive, whoever uploaded them. ## Cheap phones and slow networks Many of Kwark's people work in India on mid-range and low-end Android phones, often on metered mobile data. Design as if every byte and every database read costs the person something, because Kwark's own limits make it true for us too: the app runs inside Firebase's free tier, about 1,000 reads and 400 writes per person per day. - **One listener, shared.** Never open a database listener per module, re-read a collection to redraw a list, or upload on a timer whether or not anything changed. The same discipline that keeps Kwark free keeps a person's data plan intact. - **Write the field, not the document.** Field-path writes, change-gated background work. - **Heavy things load late.** 3D boards load three.js as a separate chunk only when a board is opened, and frames are baked to images so print, offline and the shooting book keep working. - **No server image generation.** The AI storyboard pack is exported for a tool the person chooses, partly because generating images on Kwark's servers would cost money nobody has budgeted (see [AI and authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md)). - **Phone layout is the first layout.** Wireframes start at phone size. Content by about y = 200, one 44px header, 44px targets, one floating control (Decision 0016). The calendar opens on Agenda on phones because a time grid is unreadable at 360px (Decision 0043). - **Small text is a cost.** Nothing under 12px on a phone, nothing under 11px anywhere. Cheap screens are often dimmer and less sharp. Kwark has not published measured load times or data use on low-end phones. Do not quote numbers until they are measured on a real device. ## Offline is a normal state A writer on a train, a crew on location and a student without home broadband are offline as a matter of course. Kwark treats offline as a state to describe calmly, not an error. | State | What the person sees | Where | |---|---|---| | All up to date | *Safe* | Corner sync word | | Changes waiting for the cloud | *Safe here, waiting to reach the cloud* | Corner sync word | | Working offline by choice | *Safe on this device (offline by choice)* | Corner sync word, after *Work offline* | | Saved locally, no cloud claim | *Saved on this device* | Characters, Story locations | | A write could not be stored | The page stays open and offers *Retry saving* | Characters | | No connection when signing in | *We could not reach the internet. Your work is safe on this device; try again when you are back online.* | Sign-in | In production builds a service worker caches the app shell so Kwark opens without a network. A project that has never been opened on this device, with the cloud out of reach, opens read-only and never saves over anything. - **Must** describe the state in words and say the work is safe when it is. - **Never** block writing because the network is gone. - **Never** say *failed*, *offline error* or *sync error* (Decision 0013). ## Many languages, many countries - **Indian scripts in the script.** A writer can give a character a language and type their lines on an English keyboard in Hindi, Marathi, Bengali, Tamil, Telugu, Kannada or Malayalam. The conversion happens on the device, from a fixed table; nothing the writer types leaves it. See [Writing systems](https://kwark.space/designSystem/foundations/writing-systems.md). - **Bilingual scripts.** Any line can carry a translation, and the Reader can show translations, or Devanagari in Roman letters for an actor who speaks Hindi but does not read it. - **The interface is in English today.** Localising the interface is not built. Write strings so they can be translated later: whole sentences, no words stitched together, room for text to grow by half. - **Local forms.** Money is written the way its own people write it: ₹12,50,000 for rupees, with eight currencies to choose from. Dates follow the device's locale. - **No single country's paperwork.** Unions, contracts, permits and crew rules differ by country. Never hard-code one country's rules as the default, and never call a form "standard" when it is American. ## Calm for every kind of mind Some people find counters, streaks, badges, sudden movement or a crowded screen hard to ignore; for some it is the reason they stop. Kwark is designed so nobody has to fight the interface to write. - **No streaks, no scores, no leaderboards, no "goal reached".** The rhythm widget lost its flame and moved off Home (Decision 0008), then was replaced by *Your work*, a private list of recently saved work with a link back to each, hidden until the person opens it (Decision 0036). Its empty state says *No saved changes recorded here yet* and never suggests the person has not worked: reading, rehearsing and working away from Kwark are real work. - **Nothing interrupts thinking.** The idle curtain that blanked the screen after 60 seconds was removed; it would have blanked a pitch or an animatic in a meeting (Decision 0012). - **No notifications that exist to bring people back.** - **Predictable places.** Five menus in the screenplay, always in the same order: File, Edit, Format, View, Help (Decision 0015). One floating control on a phone. The same word for the same action everywhere. - **Motion only answers an action**, and stops under reduced motion. No glows, no particles, no pulsing (Decision 0041). - **Undo instead of fear.** Prefer Undo to "Are you sure?"; deleting moves to trash. - **Fewer things at once.** Distraction-free mode (⌘⇧F) leaves the page. Structure is optional and leaves nothing behind when off (Decision 0003). - **Time without guilt.** The calendar can dim 9 to 5 for people with a day job, so evening writing blocks stand out, with no counters and no shaming (Decision 0043). ## Privacy is inclusion A person who cannot be sure their work is private cannot use the product fully. That is true for a student, for someone writing about their own family, and for anyone writing a story that would put them at risk if it were read too early. - **Work stays on the device where it can.** Indian-script typing, the calendar's quick add and the breakdown's suggestions all run on the device. - **Kwark sends no email.** After inviting someone, the sharing panel offers *Copy invite message* and *Email them* through the owner's own mail app (Decision 0042). Kwark does not hold an address book. - **Private first, shared on purpose.** Research starts in a personal workspace; sharing a board or notebook moves it to *Shared by team*. Dailies says, honestly, when it is private to the person and on this device only (Decision 0043, Dailies). - **Roles are about access, not identity.** Answering "what do you do on a film?" in Dailies never grants or removes access to a project. ## Cost is a barrier Students and indie filmmakers have little money. Every design choice that costs Kwark money per person, or costs the person money, is a choice against them. - Prefer what runs on the device to what runs on a server. - Prefer an export to a tool the person already has (their mail app, their PDF reader, their chosen AI) over a paid service inside Kwark. - Never put a basic need (exporting your own script, printing a call sheet) behind a payment. - A free web app installable on the phone first is the launch plan's recommendation, not a confirmed business model. Do not write prices or plans into the interface. ## People who write at 2am Screenplays are written over months, mostly at night, mostly by one person looking at the same rectangle. The editor's rooms exist for this. Lamplight is described in the app as *Warm brown desk, amber ink marks. Kind at two in the morning.* Midnight is *Deep blue with cool ink. Quieter than black without going cold.* - At night, nothing should flash, glow or count. - Errors at 2am must be the calmest of all: the state, that the work is safe, and one thing to do. - Cmd+S still says *Saved. Your script saves as you write.*, because a tired writer presses it anyway. See [Writing rooms](https://kwark.space/designSystem/foundations/rooms.md). ## Disability Inclusion includes disability, and the detail lives on [Accessibility](https://kwark.space/designSystem/foundations/accessibility.md): contrast in every room, a full keyboard map, screen readers, targets, motion, zoom and media. The rule here is simpler: a feature that does not work by keyboard, with a screen reader, at 200% zoom and on a phone is not finished. ## How Kwark decides: worked example **Writing rhythm on Home** (Decision 0008, then 0036). | Step | Answer | |---|---| | Who is affected | Every writer who opens Home, including first-time students | | What they were doing | Arriving to write | | What they fear | Not writing enough; being counted | | What they lose with the widget | Calm. A flame and *Goal reached* count them the moment they arrive | | What they lose without it | A private sense of rhythm, for the few who want it | | The smallest thing that helps | Keep it, private and quiet, off by default, in Settings. No flame, no streak, no resets. Remove the 60-second cloud sync, which also saves writes | | What would make us remove it | Almost nobody turns it on after a month | | What happened next | The day goal still measured attendance, and gave actors and crew nothing to do next. Decision 0036 replaced it with *Your work*: recent saved work by area and project, a link back, kept on this device, no totals, ring, target or congratulations | **Do:** A rhythm that is off by default, private, quiet, in Settings, with a remove condition written down. **Don't:** A streak on Home that is on for everyone, resets after a missed day, and sends a reminder to come back. **Do:** *Safe here, waiting to reach the cloud* while a crew member is out of signal, and the call sheet still opens. **Don't:** A red banner saying *Sync failed* and a spinner that blocks the page until the network returns. > **For agents:** - **Must** name who is affected and what they lose before proposing a change that touches people. > - **Must** default to off for anything that counts, nags, notifies or watches, and to on for anything that protects work or privacy. > - **Must** design the phone layout, the offline state and a slow network first. > - **Never** add a database listener per module, a whole-document write for one field, or a timer where an event would do. > - **Never** hard-code one country's paperwork, currency or date format. > - **Never** assume the guardian-consent or age-check flow exists in the app. ## AI readiness test **Task:** Design a reminder that helps a crew member arrive on time for Day 3 of the shoot. **Give the agent:** This page, decisions 0001, 0008, 0013 and 0042, the call sheet pattern. **Constraint:** Kwark sends no email and has no push sender; the crew member may be offline and on a cheap phone. **A reliable answer:** - Off by default and chosen by the person - Uses the person's own calendar (an .ics they add) rather than a Kwark-sent message - Works offline once added - States the call time with the day and date in words - No counters, streaks or nagging follow-ups --- # Layout > Where things go on a phone, a sideways phone, a tablet, a desk and a television, decided by one shared compact query, with the screenplay page at the centre of every one. Source: https://kwark.space/designSystem/foundations/layout ## One question, asked the same way everywhere Kwark used to ask "how wide is the window?" and got the wrong answer twice. A phone turned on its side is about 900px wide and 400px tall; it was handed the desktop, with a menu bar, the scene list and a shortcut strip over 200 pixels of page. So the question became: is this a phone, in either hand? ```js // pages/Understanding/EditorModule/hooks/useEditorLayout.ts export const COMPACT_QUERY = '(max-width: 767px), (pointer: coarse) and (max-height: 520px)'; ``` **Compact** is a narrow screen, or a touch screen too short for desktop chrome. It is the one definition of "phone" in Kwark: - In React, `useEditorLayout().compact` in the editor and `usePhoneHeader()` (from `PageHeader`) everywhere else. Both read `COMPACT_QUERY`. - In CSS, every phone rule uses exactly the same string: `@media (max-width: 767px), (pointer: coarse) and (max-height: 520px)`. `components/ui/system.css` does this for every shared control. The build fails if a rule in the screenplay module goes back to a bare `max-width: 767px`; a rule that means upright phones only must say `orientation` in its query. > **For agents:** For phone layout, use `COMPACT_QUERY` (`useEditorLayout()` or `usePhoneHeader()` in React, the identical media query string in CSS). Never use `useBreakpoint().isMobile` or a bare `max-width: 767px` for new phone rules: they miss phones held sideways. ## The ranges | Range | How it is detected | What changes | |---|---|---| | Compact: upright phones up to 767px, and any touch screen 520px tall or less | `COMPACT_QUERY` | One 44px header line, the floating dial, menus as bottom sheets, 44px targets, no breadcrumb, no rail. In the editor: one column, drawers, the writing keys docked, the timeline as a 22px strip | | Narrow: up to 1023px | `OVERLAY_NAV_QUERY`, `(max-width: 1023px)` | The scene list comes over the page as a drawer with its own open state, and goes away once a scene is chosen | | Middle: 1024–1279px | Width | Panels sit over the page inside the editor's workspace (`position: absolute`), and the page keeps a minimum of 460px | | Wide: 1280px and up | Width | Scene list, page, panel and the tool rail side by side; the page keeps at least 560px; the dial steps left of the rail | | Very large: 2400 × 1300 and up | Width and height | The page opens at Fit page instead of 100% | | Any touch | `ANY_TOUCH_QUERY`, `(any-pointer: coarse)` | An iPad with a trackpad or a touch laptop keeps the desk layout but gains touch affordances | `hooks/useBreakpoint.ts` still reports `xs` below 640, `sm` to 767, `md` (tablet) to 1023, `lg` to 1279 and `xl` above; older screens and `Modal` use its `isMobile`. It is width only, so it is right for an upright phone and wrong for a sideways one. ### Tablets A tablet upright (768–1023px) is not a phone: it gets the desktop header and menus, the scene list as an overlay drawer, and the page at full width. A tablet on its side (1024px and up) is a desk. Touch is detected separately, so a tablet's controls stay large enough for a finger where `(any-pointer: coarse)` is used. ## The screenplay at the centre Every layout in the editor is built around one rule: the page is a page. - **Width.** `min(816px, 100% − 32px)`: a US Letter page at 96 to the inch, or the room available minus a 16px gap either side, whichever is smaller. It never sits flush against the scene list or a panel. - **Indents follow the page, not the window.** The page is a container (`container-name: script-page`). Below 580px of page width (a full text column is 587px), the indents keep the printed proportions of a full column (Decision 0041). Before that fix, a narrow-page rule fired on every page, and cues sat at 2.08 inches instead of 2.2. - **On a phone** the page is the screen: no border, no corner, no shadow, 16px side padding, 20px at the head. ### Zoom: Fit width, Fit page, or a size The writer chooses how large the page is drawn (`utils/pageZoom.ts`). The page count never changes with any of it, only what fits on the screen. | Choice | What it does | |---|---| | A size | 60% to 200%, in steps of 10 | | Fit width | The page as wide as the room, less 64px | | Fit page | A whole page in the room's height (its two inch margins and its lines at 16px each), or its width if that is smaller | Fits are held between 50% and 400% and rounded down to the nearest 5%. With nothing chosen yet, a screen of 2400 × 1300 or larger opens at Fit page, because a 4K monitor or a television drew the page at a fifth of the room's width. The choice is kept on the device, not in the script. ## The editor on a desk ```html
FileEditViewToolsHelpmenu bar · z 100
timeline · z 50
Scene list
clamp(180px, 16vw, 260px), resizable
INT. EDIT SUITE – NIGHT

Mira scrubs back. Stops.

MIRA
Play it again.

page · min(816px, 100% − 32px)
Panel
beside the page at 1280px and up; over it below
``` - **The menu bar** holds five menus: File, Edit, View, Tools, Help (Decision 0015). It is the only toolbar on a desk. - **The tool rail** is 46px on the right edge with 34px buttons, shown at 1280px and up. It is the home for the editor's panels; below 1280px they move into the menus, and on a phone into the ⋯ menu. - **The scene list** is `clamp(180px, 16vw, 260px)` and the writer can drag it wider. Below 1024px it becomes an overlay. - **Panels** sit beside the page from 1280px; below that they sit over the page inside the workspace, below the menu bar, and the editor root carries `data-panel` while one is open. - **The app's quick note and comments** do not float in the editor: they are rail buttons on a desk and ⋯ menu entries on a phone. ## The production office Pre-production modules share one shell (`pages/PreProduction/shared/ProductionShell.tsx`, `ProductionOffice.css`): - **Width:** `min(1280px, 100%)`, centred, with gutters of `clamp(16px, 3.5vw, 40px)`. A module that needs more room sets `data-wide` and gets `min(1600px, 100%)`. - **Two panes:** a module whose work is two panes (the stripboard and its tray) sets `data-full` and takes the window exactly. The header is what it is, and everything left over belongs to the panes. No arithmetic against a guessed header height. - **Beside the script:** Breakdown, Shots & Boards and Schedule can open as a panel beside the live screenplay. Nothing else in the office can, because nothing else has a page to sit beside. On a phone this choice is not offered. - **Trail:** on a desk, the shared breadcrumb (`--k-crumb-*`, Decision 0044). On a phone, `PageHeader`. ## Drawers, dialogs and sheets | Surface | On a desk | Compact | |---|---|---| | `Modal` sizes `sm`, `md`, `lg` | Centred, 384, 512 or 672px wide, up to 90% of the height | A bottom sheet, up to 85–90% of the height | | `Modal` sizes `xl`, `full` | 896px, or 95% of the window | Full screen | | `Drawer` | From the right edge, 420px, the full height | Full width | | `Sheet` | Not used | From the foot, up to 560px wide and 88% of the height | | Menus | Dropdowns, 224–296px wide | Bottom sheets that drill down one page at a time | `Modal` still decides with `useBreakpoint().isMobile`, so a phone held sideways gets the centred desktop dialog. New dialogs on a phone use `Sheet` behind `COMPACT_QUERY`. ## Line lengths - Interface prose: 60–75 characters (`max-width: 70ch` is the app's usual). - The script: its format's measure, never the window's. - Settings and forms: one column of fields up to about 480px; labels above fields, not beside them, so they survive a phone and a translation. ## Print layout - The script prints on the paper chosen at export: US Letter or A4, `@page` sized to it. - Production paper (the call sheet, the one-liner) is drawn on screen at up to 900px wide (`.po-paper`) and prints at its own paper size; on a phone it runs to the screen's edges. - Chrome never prints: the dial, the beat ribbon and editor markers are hidden under `@media print`. See [Print and export](https://kwark.space/designSystem/patterns/print-and-export.md). ## Rules - **Must** use `COMPACT_QUERY` for phone layout, in React and in CSS. - **Must** keep the page at `min(816px, 100% − 32px)` and let the indents follow the page's container, never the window. - **Never** change desktop layout as part of a phone fix. Phone rules live inside the compact query. - **Always** check a layout at 375 × 812, 320 × 568, a sideways phone (about 844 × 390, touch), 1024, 1280 and 1440. - **Never** let zoom change the page count. ## AI readiness test **Task:** Add a "Notes" panel to the screenplay editor that a writer opens from the tool rail. **Give the agent:** This page, Elevation (layers), Spacing, useEditorLayout.ts. **Constraint:** It must work on a 1440 desk, a 1100 laptop, an upright phone and a sideways phone, without changing how the page is measured. **A reliable answer:** - At 1280px and up it sits beside the page and the page keeps at least 560px - From 1024 to 1279 it sits over the page inside the workspace, below the menu bar - In compact it opens as a sheet from the ⋯ menu, not from a rail - Phone detection uses COMPACT_QUERY or useEditorLayout().compact, not isMobile - The page width and indents are untouched --- # Motion > Motion in Kwark answers something a person did, lasts 120 to 320 milliseconds, eases out, and stops when reduced motion is on. Nothing moves on its own. Source: https://kwark.space/designSystem/foundations/motion ## Motion answers an action In Kwark something moves because a person did something: pressed, opened, dragged, scrolled, typed. The movement shows where a thing came from and where it went. It is never there to be looked at. - **Nothing moves on its own** in the app. No ambient animation, no idle animation, no particles, no parallax, no shimmer on a resting surface. - **The words never move.** The script, a note, a character's page: text appears where the writer put it, and stays. - **Motion is short.** A person who is writing should never wait for the interface to finish moving. Two decisions set this. Decision 0012 removed the idle curtain, which blanked the screen after 60 seconds without input; it would have blanked a pitch or an animatic in a meeting, and it interrupted thinking. Decision 0041 removed the timeline's glow, brightness filter and six rising particles from the current scene, and replaced them with a 2px ring in the project's colour. > **For agents:** Animate only in response to an input. Use `--k-dur-1` (120ms) for hover and press, `--k-dur-2` (200ms) for opening and toggling, `--k-dur-3` (320ms) for panels and sheets, with `--k-ease`. Never loop an animation in the app except a loader during a real wait. Always remove motion under `prefers-reduced-motion: reduce`. ## Durations and easing | Token | Value | For | In the app today | |---|---|---|---| | `--k-dur-1` | 120ms | Hover, press, a colour or tone change | `IconButton` and `TextButton` hover: `120ms ease` (`system.css`); timeline scene hover | | `--k-dur-2` | 200ms | Opening a menu, a switch, the dial tucking away and coming back | The dial: `transform 200ms ease, opacity 200ms ease` | | `--k-dur-3` | 320ms | Panels, drawers, sheets, the scene list opening | The scene list: `width 0.3s cubic-bezier(0.16, 1, 0.3, 1)` | | `--k-ease` | `cubic-bezier(.2, .7, .2, 1)` | Everything that enters or answers a press: fast at the start, settling at the end | — | | `--k-ease-in-out` | `cubic-bezier(.65, 0, .35, 1)` | Something moving from one place to another on screen (a card dragged and dropped into place) | — | These tokens are defined in `kwark.css` on this site. The app does not use them yet: its components write the same durations as literals (120ms, 200ms, 0.3s), and some older surfaces run longer, notably `Modal`, which fades in over 300ms and zooms in over 500ms on a desktop. New code uses the tokens; old code converges when it is touched. **Why ease out.** Something that answers a press should start at once and slow as it arrives. An ease-in start feels like lag, which is the one thing motion in a writing tool must never feel like. ### Try it ```html
--k-ease, 320ms
--k-ease-in-out
linear
ease-in, 800ms
``` Press the button, then press it again. The first row is Kwark: it leaves at once and settles. The last row is what not to do: it hesitates, then rushes, and takes long enough to notice. ## What moves, and what never does | Moves | How | |---|---| | A hover or press | Tone only (`--k-raise`), `--k-dur-1`. No scale, no lift | | A menu or popover opening | Appears at once, or fades in `--k-dur-2`. It never slides in from across the screen | | A bottom sheet | Rises from the foot, `--k-dur-3` | | A panel or the scene list | Slides open from its own edge, `--k-dur-3`, and the page makes room | | The phone dial | Tucks off the corner while the writer types or reads down the page (`translateY` plus fade, 200ms) and comes back on the way up | | A toast | Rises into place, stays, leaves | | A loader | Only during a real wait, and only after 0.4s (below) | | Never moves | |---| | The script, its line breaks and its page count | | A resting card, row, cover or poster | | Anything to attract attention: a pulsing button, a bouncing badge, a shaking field after an error | | The interface after a period of no input (Decision 0012) | | Decorative light: glows, particles, shimmer on a finished surface (Decision 0041) | A skeleton's shimmer (`.kw-skeleton`) is a loader, and is allowed only while content is actually on its way. ## The phone timeline: strip, band and bay On a phone the screenplay's timeline is three states of one thing (Decision 0007): - **Strip.** At rest it is a 22px strip under the menu: talk and action in two colours, a 2px mark where you are, a dashed line at the target length. A thumb slid along it shows a loupe with the scene, its time against the target and its length; the page jumps there when the thumb lifts. The loupe follows the finger directly, with no easing: anything else would lag behind the thumb. - **Band.** A tap on the strip, upright, opens the usual timeline band with a **Fold** button. - **Bay.** A tap on a phone held sideways opens the timeline full screen, as an edit bay, above the menu bar. Tapping a scene jumps there and folds the bay back; **Back to page** or Escape folds it without moving. The full band took a quarter of an upright phone and half a sideways one; a side reel was considered and rejected as too thin to tap. Desktops and tablets keep the band unchanged. Not yet tried on a real phone (memory note, 17 October 2026). ## Loading: no splash, no curtain Kwark used to open with a `CinematicLoader`: a full-screen black curtain for two seconds and an 800ms fade, a floating logo with a blue glow, and a random film quote. The first-run audit measured it as a 2.8-second forced splash on every open, with quotes that joked or taunted, and called it a failure of calm and honesty. It was removed in October 2026 and replaced by one loader, `SleekLoader` (`shared/SleekLoader.tsx`): - **Full screen:** the page background at once, and a small 40px Kwark mark only if the wait lasts longer than 0.4s, fading in over 0.6s and then breathing slowly. A quick load shows nothing at all. - **Small:** a 16px ring in the text colour, for a button that is working. - **Reduced motion:** the mark appears without breathing; the ring turns at a quarter of the speed. **When is a cinematic intro allowed?** Not in the app. A branded moment belongs on the marketing site or in a film the writer made, never between a writer and their script. The main checkout still mounts `CinematicLoader` in `App.tsx` as of 16 November 2026; it goes when the integration work merges. ## Reduced motion When the system asks for reduced motion: - Transitions and animations finish at once. This site's `kwark.css` sets them to 1ms under `.kw-root` and `[data-room]`; in the app about 50 files carry their own `prefers-reduced-motion` rules (the dial, the loader, the editor). - Anything that moved to show a relationship (a card sliding into its new act) still ends in the right place; it just does not travel. - Nothing that carries meaning is lost. If a state was shown only by motion, it was never shown properly; give it a word or a mark. ## Rules - **Must** answer an input. **Never** start an animation on a timer or on idle. - **Must** use `--k-dur-1`, `--k-dur-2` or `--k-dur-3`. **Never** exceed 320ms for interface motion. - **Always** ease out with `--k-ease` for anything entering or answering a press. - **Never** animate the script's text, its layout or its page count. - **Never** use a splash screen, a curtain or a forced intro. - **Always** honour `prefers-reduced-motion`, and test with it on. **Do:** The scene list slides open from the left over 320ms with `--k-ease`, and the page moves to make room. Under reduced motion it is simply open. **Don't:** A dialog that zooms in from 95% over 500ms, a card that bounces when dropped, a field that shakes on a wrong password. ## AI readiness test **Task:** Animate a scene card moving from Act 1 to Act 2 in the outline when the writer drags and drops it. **Give the agent:** This page, Elevation, the outline's card markup. **Constraint:** It must feel immediate, and work for a person with reduced motion turned on. **A reliable answer:** - The card follows the pointer directly while dragging, with no easing - On drop it settles into place with --k-ease-in-out over --k-dur-3 or less - The lifted card uses --k-shadow-pop only while it floats - Under prefers-reduced-motion it lands in place with no travel - Nothing else on the page animates --- # Design principles > The rules Kwark decides by, each with its reason, what it changes on screen, where it shows in the app and the trade-off it settles. Source: https://kwark.space/designSystem/foundations/principles ## What these are for Kwark's mission is short: help people who want to write feel calm, begin writing and keep writing, then help the same people take that work into production. Every principle below protects one half of that sentence. They are not values to put on a wall. Each one has already decided a real argument in the app, and each one is recorded in a decision (`docs/ux/decisions`) that says what evidence would make us change it. Read a principle as a test you can run on a screen. If a screen fails it, the screen changes, not the principle. > The specimen above is what the principles sound like in practice. Cmd+S says *Saved. Your script saves as you write.* (Decision 0014). The sync word says *Safe* before it says anything else (Decision 0013). The app never says *failed* to a writer. ## The writer first **The rule.** Empathy for the person using Kwark outranks every other consideration: ours, a competitor's, a producer's, the tidiness of the code. **Why.** A writer sitting down to write is often unsure and sometimes afraid. The product's first job is not to add to that. Calm is a measurable property of a screen, not a mood. **What it changes.** Every review starts with the empathy checklist from *How we decide*: who is this for and what were they doing a minute ago; what are they afraid of right now; what is the smallest thing that helps; what are we making them look at that is not their work; what can they not undo. **In the app.** Writers press Cmd+S out of habit. It used to make a snapshot, which cluttered the history and reassured nobody. Now it shows *Saved. Your script saves as you write.*, and restore points moved to Cmd+Shift+S (Decision 0014). The habit is honoured instead of corrected. **The trade-off it settles.** Habit against model purity. The "correct" model says autosave makes Cmd+S meaningless. The writer's hands say otherwise. The writer wins. ## A safe, private place **The rule.** Nothing public, ranked or compared inside Kwark. No competitions, leaderboards, public counts, badges that compare people or marketplaces (Decision 0001). Anything social belongs on Bekwarky, a separate site. **Why.** A writer who feels watched writes less, or not at all. People bring dream projects here. **What it changes.** Private by default. New collaborators join as Readers, and the request link is off until the owner turns it on (Decision 0042). Personal features may exist only when they face inward: a rhythm only the writer can see is allowed; a public word count is not. **In the app.** The Home writing-rhythm widget had a flame and *Goal reached*. It was a streak in disguise, counting a nervous writer the moment they arrived. It was turned off by default and moved to Settings with no flame, no streak and no resets (Decision 0008), then replaced by *Your work*: a private list of recently saved work with a link back, hidden until opened, with no totals, rings, targets or congratulations (Decision 0036). **The trade-off it settles.** Engagement against safety. Streaks bring people back; they also make missing a day feel like failing. Kwark gives up the retention trick. ## Measure the work, never judge it **The rule.** Kwark never scores, grades, critiques or rewrites a person's story, by machine or by metric (Decision 0002). It may help them see the work: runtime, pages, talk against action. It never says the work is good or bad. **Why.** We would be grading people's stories with a machine we cannot defend to a producer or to the writer. Competitors sell AI coverage; that is not a reason. **What it changes.** A number must describe, not evaluate. *Runs about 1 h 42 min* is a measurement. A green tick beside a "healthy" runtime is a verdict. The question to ask of any figure: does it measure the work, or rate it? **In the app.** The timeline shows each scene's estimated length and whether it is mostly dialogue or mostly action, and the balance card says *Talk 62% · Action 38%*, with no target range and no colour for good or bad. The idea module's *Conviction %* and the outline's trophies were recorded as deviations to remove. **The trade-off it settles.** Helpfulness against authorship. Some writers would like a verdict. Kwark refuses to give one, and gives them a clear look at their own work instead. See [AI and authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md). ## Nothing compulsory **The rule.** Every structure-aware feature (beat sync, the outline rail, act assignment, breakdown tags, targets, rhythm) is opt-in and can be switched fully off at any time (Decision 0003). A switch that cannot turn a feature fully off is a bug. **Why.** Some writers want an outline wired to the page. Some want an empty page. Forcing the outline degrades the writer who just wants to write. **What it changes.** Features are designed off first, then given a switch. Turning a feature off must leave nothing behind on the page: no empty rail, no faded markers, no "you turned this off" banner. **In the app.** The ⟷ after an act name means *this act is linked to the outline*. It sits beside the act name, takes no line and never prints (Decision 0041). With linking off it is not there at all. **The trade-off it settles.** Discoverability against freedom. An off-by-default feature is found by fewer people. Kwark accepts that, because a feature that is forced on loses the writer it was not built for. ## Structure, not teaching **The rule.** Every field feeds a real artefact: a list, a sheet, a date, a cost. No coaching prompts, theory engines, quizzes or "meanings" (Decision 0004). **Why.** Kwark's people are part-time filmmakers. They need working structure, not film school. Teaching patronises and clutters. **What it changes.** Before adding a field, name the artefact it ends up in. If the answer is "it helps them think", the field does not ship. **In the app.** Empty outline cards used to ask questions by story position ("What does an ordinary day look like before anything changes?"). They were coaching inside a field. An empty card now says *Add words…* (Decision 0004, history, 4 November 2026). The Enneagram quiz, tension sliders and camera "meaning" engines are listed as deviations. **The trade-off it settles.** Guidance against respect. A beginner might like prompts. The page treats them as a filmmaker anyway, and the help they get is a structure that works. ## Paper and digital as one act **The rule.** Where film already has a paper artefact (the marked-up script, the breakdown sheet, the stripboard, the call sheet), the digital version *is* that artefact, built in the same act, not a table beside it (Decision 0005). **Why.** A crew already works from paper. A table alone is not something a crew will accept on set. **What it changes.** Print and PDF are first-class, designed with the screen, not exported as an afterthought. Every script-bound module answers "what paper thing does this replace, and can it print?" **In the app.** The screenplay page on screen is the printed page, measured: dialogue wraps at 33 characters as Highland's printed pages do, cues sit where the PDF puts them, and nothing appears on screen that the PDF does not have (Decision 0041). Issuing a call sheet makes a numbered revision and says *Rev 2 issued. Save it as PDF to send it to the crew.* (Decision 0020). **The trade-off it settles.** Freedom of screen design against trust. A screen-only layout could be prettier. If the screen and the PDF disagree, the writer stops trusting the page count, so the screen gives way. ## Competitors are the floor **The rule.** Parity with Final Draft, Highland, Celtx or Arc Studio is the minimum, never the reason. Every plan leads with what no competitor does: one script feeds everything (Decision 0006). **Why.** Chasing parity makes Kwark a worse copy of someone else. **What it changes.** A feature request that starts "X has it" is sent back to step one: name the person, the situation and the problem. Competitors set the quality bar for what Kwark already does; menus must feel at least as professional as Final Draft's (five menus, Decision 0015). **In the app.** The breakdown is read off the script, the schedule from the breakdown, the call sheet from the schedule and the budget from the cast and locations (Decision 0022). Nobody retypes a scene. **The trade-off it settles.** Familiarity against direction. Kwark matches the conventions writers know (Tab cycles elements, scene numbers, revision colours) and spends its invention where competitors stop. ## Honest and quiet **The rule.** Say what is true, in plain words, calmly. Tell the state first; then what happened; then that the work is safe, if it is; then what to do (Decision 0013). Never *failed*. **Why.** When something goes wrong, the writer's first fear is for their work. Raw errors and *An error occurred* make that fear worse and give them nothing to do. **What it changes.** Library text never reaches a person. `friendlyError()` turns every Firebase code into one calm sentence and replaces anything it does not recognise with *Something went wrong. Your work is safe; please try again.* Words are checked against the test: would we say this out loud to a nervous writer? **In the app.** The corner sync word reads *Safe*, *Safe here, waiting to reach the cloud* or *Safe on this device (offline by choice)*. Characters and Story locations say *Saved on this device* after a local write, which makes no cloud claim, and offer *Retry saving* if a write could not be stored (Decision 0013, history). **The trade-off it settles.** Precision against calm. Engineers want the real error text. Writers need the state. The real text goes to the console; the writer gets the truth in their own words. See [Content](https://kwark.space/designSystem/foundations/content.md). ## Their work is never at risk **The rule.** Autosave, undo, recoverable trash, honest sync state and tested backups. A feature that can lose work does not ship. **Why.** A phone that opened a light project card once saved a placeholder over ten real pages. Data loss became priority one. **What it changes.** Every feature answers the work-is-safe test: if this fails, loses connection or is interrupted halfway, what happens to the writing? Prefer Undo to "Are you sure?". Deleting moves to trash. Every screenplay save carries a revision stamp, and a save that would overwrite a newer copy from another device is refused and kept for recovery. **In the app.** A character edit that cannot be stored keeps the page open: *This change has not saved yet, so the page stays open. A copy is kept on this device.* Back waits for the local save. **The trade-off it settles.** Speed against safety. A save that waits, a page that stays open, a conflict banner: each costs a moment. None is negotiable. ## Everything has a meaning **The rule.** Every small thing on screen that carries meaning (a dot, a badge, a count, a colour, an edge, an icon with no label) has a row in the element register: what it means, when it appears, what the person should do about it, and why it earns its place. A dot with no reason is removed. **Why.** Unexplained marks make people wonder whether they did something wrong. One mark meaning two things is worse. **What it changes.** A new mark needs a register row before it ships. One mark, one meaning: on the story spine a dot is a beat, nothing else (Decision 0031). On the timeline, the 2px ring in the project's colour means *the scene the caret is in*, and so does the pointer above it (Decision 0041). **The trade-off it settles.** Richness against clarity. Designers like to add signals. Each one costs attention, so each one has to justify itself in writing. ## One job, one look **The rule.** From `docs/design-system.md`: - If two things look different but do the same job, one of them is wrong. - If it is clickable, it is a button (the shared `Button` or `IconButton`). - A component does not choose its own colour, font, size or spacing; it takes them from the tokens. - Content a writer chooses (fonts in the reader, rooms in the editor) is not interface and may differ; everything else is the system. **Why.** Inconsistency is a tax on every screen: people relearn the same control in each module. It also makes the product look unfinished, which costs trust. **What it changes.** Before building, check the shared components. The build counts hard-coded colours, fonts and sizes per file and fails when a file gets worse. Old code moves to the system when someone touches it. **In the app.** The unified breadcrumb and dropdowns replaced several look-alike versions across modules (Decision 0044). Rooms are allowed to differ because a writer chose them; a module that invents its own grey is not. **The trade-off it settles.** Local polish against coherence. A module may break the pattern where the craft asks for it (Research may feel like research), but the exception is recorded, never accidental. ## Content first, especially on a phone **The rule.** On a phone, one 44px header line, content by about y = 200, rows without buttons, one floating control (Decision 0016). **Why.** A phone screen is small and the work is the point. Breadcrumbs, subtitles and rows of chips above the fold push the work out of sight. **What it changes.** Above the fold: the header and at most one 40 to 48px band. Secondary actions go into the row's ⋯ sheet. Comments, Quick note and Account are items of the one floating dial. See [Phones](https://kwark.space/designSystem/patterns/phones.md). **In the app.** The phone timeline rests as a 22px strip under the menu; slide a thumb to scrub, tap to open, turn the phone sideways for a full-screen bay (Decision 0007). **The trade-off it settles.** Reach against room. Fewer controls are visible at once; everything is still one tap away. ## Flat and legible **The rule.** No glows, gradients, blurred blobs, sparkles or decorative light. Depth is a line and a step in tone. Shadows only for things that float. **Why.** Writers spend hours in the editor. Their reference points (Final Draft, Highland, WriterSolo, Fade In) use flat desks. Glow pulls the eye from the words and costs contrast. **What it changes.** The editor's rooms lost their light layer; the timeline's current scene lost an 18px glow, a brightness filter and six rising particles (Decision 0041). The founder removed the modal's accent glow and asked for no lighting glow anywhere in the app. **In the app.** Each room keeps its desk, paper, ink and pencil and nothing else. See [Writing rooms](https://kwark.space/designSystem/foundations/rooms.md). **The trade-off it settles.** Atmosphere against seriousness. If writers ask for the atmosphere back, it returns as an opt-in room, never the default. ## Works for everyone, everywhere **The rule.** Phones as well as laptops; keyboard and screen reader; slow or no network; Indian scripts; unions and paperwork that differ by country. **Why.** Kwark's people include students from 13 up, indie crews on short shoots, and writers whose characters speak Tamil or Hindi. A product tested only on a fast laptop in English fails most of them. **What it changes.** The everyone test runs on every screen: phone, tablet, laptop; keyboard only; screen reader; offline; a script in Tamil; a user in another country. See [Accessibility](https://kwark.space/designSystem/foundations/accessibility.md), [Inclusive design](https://kwark.space/designSystem/foundations/inclusive-design.md) and [Writing systems](https://kwark.space/designSystem/foundations/writing-systems.md). **In the app.** Typing a character's lines in their own script on an English keyboard happens on the device, with nothing sent anywhere. Money is written the way its own people write it: ₹12,50,000 in India. **The trade-off it settles.** Speed of shipping against reach. Some features ship later because they must work on a phone and offline first. ## A problem before a feature **The rule.** Nothing a person will see is built until the need, the journey and a phone-first wireframe are agreed. "A competitor has it" is not a need. **Why.** Features built from a guess add surface without helping anyone, and every surface costs calm. **What it changes.** The order of work in [UX before build](https://kwark.space/designSystem/method/ux-before-build.md). Every decision record ends with *What would make us remove it*; a feature that cannot be removed is a liability. **In the app.** The AI storyboard pack was agreed as an idea on 29 September 2026, but it is not built: its journey still needs the founder's agreement. ## When principles pull apart The decisions so far show how conflicts have been settled. Use them as precedent. | Conflict | How it was settled | Record | |---|---|---| | A private rhythm helps some writers; any count can feel like judgement | Off by default with no flame or streak, then replaced by a private record of saved work that counts nothing | 0008, 0036 | | Room atmosphere against a flat, serious page | Flat by default; atmosphere only as an opt-in | 0041 | | Real error text (precision) against calm | Calm sentence for the person; detail in the console | 0013 | | Teaching beginners against respecting filmmakers | No coaching in fields; any teaching would be a separate opt-in place | 0004 | | Feature parity against direction | Parity is required, never the lead | 0006 | | Speed of a save against certainty | The page waits for the local save | 0013 history | When a new conflict is not covered, do not guess. Write down two or three options with their costs, recommend one, and let the founder decide. **Do:** Measure and show: *Scene 12 · INT. EDIT SUITE – NIGHT · 2:40 · mostly dialogue*. The writer decides what it means. **Don't:** Judge: a red bar on Scene 12 because it is "too long", a pacing score, or a tip on how to fix Act 2. **Do:** Hidden until the person opens it, private, counting nothing: *Your work*, with *No saved changes recorded here yet* when it is empty. **Don't:** On for everyone, a flame on Home, *Goal reached* after 500 words and a streak that resets. > **For agents:** - **Must** run the calm test on anything you add: does it count, grade, warn, nag or ask for attention it has not earned? > - **Must** name the real artefact (a sheet, a list, a date, a cost) every new field feeds. > - **Must** make every structure-aware feature switchable fully off. > - **Never** score, grade, rank or judge a person's writing, or show a "good range" beside a measurement. > - **Never** add social, public or comparative features inside Kwark. > - **Never** justify a change with "a competitor has it". > - **Always** cite the decision record a rule comes from, and propose a new record when you change a rule. ## AI readiness test **Task:** Propose a "progress" panel for the project overview of Blank Pages, the demo project. **Give the agent:** This page, decisions 0001, 0002, 0003, 0008 and 0036, the element register. **Constraint:** Show the writer where the work stands without counting, grading or comparing them. **A reliable answer:** - Measures only (pages, scenes, estimated runtime) with no target colours or verdicts - No streaks, goals, flames or percentages of "done" - Off or quiet by default, and switchable off - Every number has a register row saying what it means - Cites the decisions it follows --- # Radius > Four corners, each for one kind of thing, a rule for corners inside corners, and the paper that is never rounded more than paper is. Source: https://kwark.space/designSystem/foundations/radius ## Four corners A corner says what kind of thing something is. A field and a button have small corners because they are small and precise; a card has a softer corner because it holds several things; a sheet or dialog has the softest because it is a surface laid over the page. A pill is a token you pick up and put down. Four sizes, and every rounded thing in Kwark takes one of them. | Token | Value | For | Examples in the app | |---|---|---|---| | `--k-radius-control` | 6px | Things you press or type into | `Button`, `IconButton`, `TextButton`, inputs, menu items, breadcrumb items (`--k-crumb-radius`) | | `--k-radius-card` | 10px | Things that hold other things | Cards, dropdown menus (`DropdownMenu.css`), the segmented control's track, the timeline loupe | | `--k-radius-sheet` | 14px | Surfaces laid over the page | Dialogs on a desktop (`Modal`), the phone bottom sheet's top corners (`.k-sheet`), the phone tools menu in the editor | | `--k-radius-pill` | 999px | Tokens and the round buttons | `Chip`, badges, the phone dial and its items, the sheet's grab handle, the loader ring | There is no 4, 8, 12 or 16 among them for interface surfaces. Paper has its own corner (below). > **For agents:** Use `--k-radius-control`, `--k-radius-card`, `--k-radius-sheet` or `--k-radius-pill`. Never write a `px` radius in a component, except inside a nested element where the rule below gives a calculated one, and then write it as `calc()` of the token. ## Corners inside corners When a rounded thing sits inside another with padding around it, the inner corner is the outer corner minus the padding. Otherwise the gap between the two curves is thicker at the corner than along the sides, and the inner shape looks pinched. **inner radius = outer radius − padding** Kwark already does this in two places, and both are the reference: - **Segmented control.** The track has `--k-radius-card` (10px) and 2px of padding; each choice has `calc(var(--k-radius-card) - 2px)`, 8px (`components/ui/system.css`). - **Screenplay timeline.** The track has an 8px corner; each scene block sits 3px in and has a 5px corner (`editor.css`, `.timeline-bar__track` and `.timeline-bar__scene`). If the padding is equal to or larger than the outer radius, the inner element is square or takes `--k-radius-control`, whichever is larger. A 16px-padded card never has 0px corners on the button inside it; the button keeps its own 6px. ```html
``` The first two follow the rule. The third puts a 10px corner 8px inside a 10px corner: look at how much thicker the gap is at the corners than at the sides. ## Paper is paper A sheet of paper has a corner of almost nothing. Everything in Kwark that stands for a printed page keeps that. - **The screenplay page** has a 4px corner on a desktop and is square on a phone, where it runs to the edges of the screen (`editor.css`: `border-radius: 4px` inside the desktop query, `0` inside the compact query). - **The call sheet and other production paper** (`.po-paper`) are the same: 4px on a desk, square on a phone. - **Stripboard strips** are 5px, with the grip at the strip's left end rounded only on its outer side (`5px 0 0 5px`) so the two read as one strip. - **Timeline scene marks on the phone strip** are square, so one scene butts against the next without a gap that would read as a pause. The rail they sit on is 3px. **Never** give a page, a call sheet, a strip or a storyboard panel a card's 10px corner. It turns a document into a widget. ## What is never rounded - The edge of the screen. A sheet that rises from the bottom of a phone has rounded top corners and square bottom ones; a full-screen panel is square. - Table cells, grid lines and the stripboard's day breaks. - The focus ring's own shape: it follows the element's corner, plus its 2px offset. - Text selection, the caret and revision marks in the script. - A full-bleed image. A poster or a storyboard frame inside a card takes the card's corner minus its padding, or no corner if it touches the card's edge, with `overflow: hidden` on the card. ## Known differences in the app - The `Modal` on a phone becomes a bottom sheet with 32px top corners (`rounded-t-[2rem]`), not `--k-radius-sheet`. The newer `Sheet` uses the token. New work uses `Sheet`. - The toast uses a 12px corner (`rounded-xl`), between card and sheet. It should take `--k-radius-card`. - The editor's tool rail buttons use 9px. They should take `--k-radius-control` or `--k-radius-card`. These are recorded so nobody copies them; they are fixed when the file is next touched. **Do:** A dialog at 14px containing a 6px text field and two 6px buttons. A list inside a 10px card whose first and last rows are clipped by the card (`overflow: hidden`), not rounded themselves. **Don't:** A dialog at 24px with 12px fields and pill buttons, so every element has a different corner and nothing reads as part of the same object. ## AI readiness test **Task:** Design a "Scene 12" card for the outline's index-card view with a header strip, the scene's summary, and two buttons inside it. **Give the agent:** This page, Spacing, Elevation. **Constraint:** Use only the four radius tokens and calc() from them. The card must look like it belongs beside the existing outline cards. **A reliable answer:** - Card uses --k-radius-card (10px) and no shadow at rest - Header strip touches the card edge and is clipped by overflow hidden, not separately rounded - Buttons keep --k-radius-control (6px) - Any inset element uses calc(var(--k-radius-card) - padding) - No 4px or 12px literal values --- # Writing rooms > The screenplay editor's five rooms (Studio, Daylight, Paper, Lamplight, Midnight): what each is made of, how every colour in the editor is worked out from it, the legibility maths, and the rules for building inside one. Source: https://kwark.space/designSystem/foundations/rooms ## A room is not a colour A screenplay is written over months, mostly at night, mostly by one person looking at the same rectangle. What that rectangle looks like matters more than almost anything else in the editor. "Dark or light" is not much of an answer, and neither is a list of eleven colour pickers. So the editor has five rooms, and one of the writer's own. A room is a **desk**, a **sheet of paper** on it, the **ink**, the **pencil** that marks what is active, whether the paper has a **tooth**, and what the **index cards** are cut from. Each is chosen for the others. The chrome, the timeline, the overview and the cards are all worked out from that one set (`paletteFrom()` in `pages/Understanding/EditorModule/utils/editorTheme.ts`), so nothing in the room is left in another room's colours. Legibility is measured, not assumed. Every ink is settled against the grounds it sits on, so a pale room cannot leave its labels grey on grey. A writer picks a room from **View › Room…** in the screenplay. The choice is content, not interface: `docs/design-system.md` says that what a writer chooses (rooms in the editor, fonts in the reader) may differ from the system. Everything else inside the editor takes the room's roles. ## The five rooms | Room | `id` in code | What the app says about it | |---|---|---| | Studio | `dark` | A dark room with the page lifted just off the desk, marked in your project's colour. | | Daylight | `light` | White paper on a cool grey desk, blue pen. The script as it will print. | | Paper | `paper` | Cream stock with a tooth to it on a kraft desk, and a script editor's red pencil. | | Lamplight | `sepia` | Warm brown desk, amber ink marks. Kind at two in the morning. | | Midnight | `slate` | Deep blue with cool ink. Quieter than black without going cold. | Studio is the default (`DEFAULT_THEME`). The ids are older than the names and are kept because they are stored in writers' settings; never show an id to a person. | Room | Desk (`--k-bg`) | Chrome (`--k-surface`) | Page | Ink (`--k-text`) | Pencil (`--k-accent`) | |---|---|---|---|---|---| | Studio (`data-room="studio"`) | #0f0f11 | #151518 | #1a1a1d | #e8e6e3 | #e8b58b | | Daylight (`data-room="daylight"`) | #e6e9ee | #f4f6f8 | #ffffff | #181b21 | #2f55c0 | | Paper (`data-room="paper"`) | #d6ccb8 | #e6dece | #f8f2e4 | #28221a | #a3352b | | Lamplight (`data-room="lamplight"`) | #16110d | #1d1712 | #251e18 | #eddcc3 | #e0a24e | | Midnight (`data-room="midnight"`) | #0b111b | #101826 | #141e2e | #dde6f2 | #7fb5e8 | ## Every value | | Studio | Daylight | Paper | Lamplight | Midnight | |---|---|---|---|---|---| | Desk | `#0f0f11` | `#e6e9ee` | `#d6ccb8` | `#16110d` | `#0b111b` | | Chrome | `#151518` | `#f4f6f8` | `#e6dece` | `#1d1712` | `#101826` | | Page | `#1a1a1d` | `#ffffff` | `#f8f2e4` | `#251e18` | `#141e2e` | | Ink | `#e8e6e3` | `#181b21` | `#28221a` | `#eddcc3` | `#dde6f2` | | Pencil | project colour | `#2f55c0` | `#a3352b` | `#e0a24e` | `#7fb5e8` | | Grain | no | no | yes | no | no | | Card stock | `#222226` | `#ffffff` | `#fbf7ec` | `#2e251d` | `#1a2536` | | Card rule | project colour | `#d9534f` | `#c0453a` | `#e0a24e` | `#7fb5e8` | Studio names no pencil, so it wears the project's own colour: the caret, the selection and the scene you are in are drawn in whatever colour the writer gave the project. In this design system's `kwark.css`, Studio's `--k-pencil` is set to `#e8b58b`, the app's default dark accent, which is what Studio shows when a project has no colour of its own. Paper's grain is drawn, not loaded: a small SVG noise filter at 7% opacity tinted toward brown, so the stock has a tooth without an image request. ## How the roles follow the room Put `data-room` on the editor's container and the design system's roles take the room's values. In the app the same thing happens through `--editor-*` variables set from `paletteFrom()`. | Role in this system | Room part | App variable | Use | |---|---|---|---| | `--k-bg` | Desk | `--editor-bg` | Around the page | | `--k-surface` | Chrome | `--editor-surface` | Menus, navigator, rails | | `--k-page` | Page | `--editor-page-bg` | The sheet | | `--k-text` | Ink | `--editor-text` | The words | | `--k-text-2` | Settled muted ink | `--editor-text-muted` | Meta, scene numbers, rail labels | | `--k-accent` | Pencil | `--room-caret`, `--project-accent` | Caret, selection, current scene, primary action | | `--k-on-accent` | Desk | `--project-accent-text` | Text on a pencil-coloured fill | | `--k-line` | Ink mixed into chrome | `--editor-border` | Hairlines | A shared component placed inside the editor (a menu, a dialog, a toast) therefore takes the room's colours without knowing it is in one. That is the point: one Button, five rooms, no branches. ```html

INT. EDIT SUITE – NIGHT

Mira scrubs back. Stops.

MIRA

I didn’t shoot this.

Scene 12 · 2:40 ``` ## What is worked out from the room `paletteFrom()` takes the room and returns about forty variables. The ones that carry meaning: | Variable | Worked out as | Why | |---|---|---| | Muted ink | Ink faded toward the chrome until the worst of chrome, desk and page reaches 5.2:1 | Quiet labels that still read on every ground | | Faint ink | The same, to 3.2:1 | Marks that are present but not text | | Border | Chrome with 13% (dark) or 15% (light) of the ink | A line that shows on every room | | Warning | `#d8a44a` pushed toward the ink until 4.5:1 | Warnings that read on Paper as well as Midnight | | Input background | Chrome lifted 5% toward the ink (dark) or 70% toward white (light) | Fields that look like fields | | Popover background | Chrome lifted 3.5% (dark) or 82% (light) toward white | Menus a step above the chrome | | Active row | Chrome with 12% (dark) or 10% (light) of the ink | Hover and pressed states | | Page edge | Page 7% toward white (dark) or 9% toward black (light) | The sheet's outline on the desk | | Card muted ink | Ink settled against the card stock to 5:1 | Index card meta | | Timeline talk and action | See [timeline marks](#timeline-marks) | Each scene carries its own number | | Overview marks | Scene `#d9a24a`, action `#6aa6d8`, dialogue `#7fb86a`, each pushed toward the ink until 3:1 on the page | The overview's highlighting stays visible on any paper | | Selection | The pencil at 30% (dark) or 22% (light) alpha | Selected text stays readable | | Caret | The pencil, or the project's colour | The one thing that moves | ## The legibility maths Four small functions do the work. They use the WCAG relative-luminance formula, so the numbers mean the same thing an accessibility checker means. **`readableOn(ground)`.** Ink that can be read on a ground. It measures both white and near-black (`#0b0b0b`) against the ground and takes the better one. It does not ask "is this ground dark?", because a mid-grey reads as dark on that test and yet takes black ink far better than white (5.3:1 against 3.9:1): a threshold picks the worse of the two exactly where the choice is hardest. Then it carries up to 16% of the ground into the ink, in 4% steps, but only as much as still keeps 7:1. The page looks like one room instead of a rectangle with text stuck on it. **`settle(ink, grounds, target)`.** A quieter ink. A fixed fade (say 40% toward the ground) is a whisper on black and illegible on white, so the amount is found by binary search, fourteen steps, against every ground the label may sit on, and the worst ground decides. Muted ink targets 5.2:1, faint 3.2:1; with Stronger contrast, 7:1 and 4.6:1. **`legible(colour, ink, grounds, target)`.** A colour pushed toward the ink, 10% at a time, until it can be read as text on these grounds. Used for the pencil when it colours text (4.6:1), for warnings (4.5:1) and for overview marks (3:1). **`carrying(fill, ink, ground, target)`.** A fill pushed toward its ground, 10% at a time, until the ink on top of it reads. Used for the timeline's scene blocks, which carry their own numbers. Two helpers sit around them: `isDark(colour)` (relative luminance under 0.42) chooses which set of light-appearance rules the editor's stylesheet applies, and `readsWell(ground)` says whether a ground can carry a comfortable read at all (4.5:1 with its best ink). The custom-room picker uses the second to warn a writer. ### What the maths produces | Room | Ink on page | Ink on desk | Muted text on chrome | Pencil on page | |---|---|---|---|---| | Studio | 13.9:1 | 15.4:1 | 7.2:1 | project colour, made legible to 4.6:1 | | Daylight | 17.2:1 | 14.2:1 | 6.6:1 | 6.6:1 | | Paper | 14.1:1 | 9.9:1 | 5.7:1 | 6.1:1 | | Lamplight | 12.2:1 | 14.0:1 | 7.4:1 | 7.4:1 | | Midnight | 13.3:1 | 15.0:1 | 7.6:1 | 7.7:1 | Muted values here are the ones in `kwark.css`; the app settles its own at runtime against all three grounds and never goes under 5.2:1. ## Timeline marks The timeline under the page is a strip of scenes coloured by what fills them: **talk** and **action**. Each block carries its own number, so the fill is pulled toward the page until the ink reads on it (`carrying`, 4.5:1 on light rooms, 5:1 on dark). A scene that is both is drawn half and half. Each room ships five pairs, chosen for its desk. The first pair is the room's default, and its preview in the picker shows that strip. | Room | Pairs (talk and action) | |---|---| | Studio | Amber and graphite · Teal and graphite · Indigo and taupe · Plum and slate · Moss and stone | | Daylight | Clay and sand · Sea and linen · Lavender and stone · Rose and cream · Cornflower and stone | | Paper | Terracotta and kraft · Verdigris and oat · Ink blue and kraft · Ochre and pewter · Dusty rose and oat | | Lamplight | Amber and walnut · Copper and umber · Petrol and walnut · Olive and umber · Rose and walnut | | Midnight | Moon blue and slate · Teal and slate · Lilac and slate · Sandstone and slate · Dusk rose and slate | Default pairs, as hex: | Token | Name | Light | Dark | Use | |---|---|---|---|---| | `#b98545` | Studio talk · Amber | #b98545 | | Action is graphite #45484e | | `#d9a58c` | Daylight talk · Clay | #d9a58c | | Action is sand #dcd2bd | | `#c98e72` | Paper talk · Terracotta | #c98e72 | | Action is kraft #d3c8b0 | | `#c9953f` | Lamplight talk · Amber | #c9953f | | Action is walnut #4a4038 | | `#5f8fc0` | Midnight talk · Moon blue | #5f8fc0 | | Action is slate #2e3a4c | **Light rooms use pastels a shade deeper.** On a pale room the strip is two pastels set about 20% darker in lightness than a pastel usually is, hue and saturation kept, so they hold against white without turning into blocks of colour. The sand stays sand and never drifts into tan. Rejected on the way, and not to be revived: plain pastels (washed out), saturated blue with white numbers, anything mixed toward black (dirty), and grey chips with an accent underline (hard to read). Dark ink stays on the fills: Daylight's clay carries 8.0:1, its sand 11.5:1. **Dark rooms derive talk from the pencil.** With no pair chosen, talk is the pencil mixed halfway with the page, and action is the ink mixed 72% toward the page, both then carried to 5:1. **The current scene** is a 2px ring in the project's colour with a pointer above it. It used to have an 18px glow, a brightness filter and six particles rising through it on a loop. They are gone (Decision 0041). ### Card and mark swatches Each room also ships twelve swatches for marking index cards (times of day, lenses) and characters, named for the room: Studio from Terracotta to Slate, Daylight from Clay to Slate, Paper from Terracotta to Pewter, Lamplight from Copper to Umber, Midnight from Dusk rose to Deep slate. A writer chooses from the room's own set, so a colour that suits Paper is never dropped into Midnight. ## Stronger contrast A switch in the room picker: *Stronger contrast. Fuller ink and firmer lines, in whichever room.* With it on: - ink becomes pure white or pure black, whichever scores better against desk, chrome and page together; - muted ink targets 7:1 and faint 4.6:1; - borders take 30% of the ink instead of 13 to 15%; - the page edge is drawn three times firmer; - pencil text targets 7:1. It is not a room. It works in any of them, including one the writer mixed. ## A room of the writer's own A writer can name one colour, the desk, and optionally a pencil. `customRoom()` builds the rest the way the shipped rooms are built: - chrome is the desk lifted 3.5% toward white (dark desk) or 35% (light desk); - the page is the desk lifted 6% (dark) or 72% (light); - ink is `readableOn(page)`, or `readableOn(desk)` if that ink would fall under 4.5:1 on the desk; - card stock is a step off the page; the card rule is the pencil, or the project's colour. If the desk is too close to the middle for anything to read well, the picker says so plainly: *That desk is close to the middle, so nothing reads really well on it.* It then explains that the sheet is lifted off it to keep the script readable but the menus will be tiring. The writer may keep it. A writer can also save a mixed room under a name. ## Rooms that moved Earlier rooms were folded into the five. People who chose them are moved, not reset: | Old room | Now | |---|---| | Moss | Midnight | | Contrast | Studio, with Stronger contrast on | | Notebook | Paper | | Typewriter | Lamplight | ## Flat rooms and the printed page Decision 0041 (12 November 2026) settled two things after the founder's audit: "I can see glow in some themes and not sure if writers would appreciate it… make sure we aren't off by even 1px." **Rooms are flat.** Each room keeps its desk, paper, ink and pencil; the light layer that put a window, a lamp or a moon over the desk is removed, and the room notes no longer mention one. Writers' reference points (Final Draft, Highland, WriterSolo, Fade In) use flat desks. If writers ask for an atmosphere they miss, it comes back as an opt-in room, never the default. The Reader's opt-in *Printed book* style keeps its lit desk, because it is chosen, not default. **The screen is the printed page.** A room changes colour only. It never changes geometry: - dialogue wraps at 33 characters and parentheticals at 28, as Highland's printed pages do (3.3 and 2.8 inches); - the narrow-page rule fires below 580px; a full text column is 587px, so it no longer fires on every page; - scene headings sit on the action margin (each heading's chevron returned the 5px it borrowed); - a linked act's ⟷ sits beside the act name and takes no line, so the screen has no line the PDF does not. ## Building inside a room > **For agents:** - **Must** use role tokens (`--k-bg`, `--k-surface`, `--k-page`, `--k-text`, `--k-text-2`, `--k-accent`, `--k-line`) for anything inside the editor; never a hex value and never a theme check. > - **Must** keep `data-room` on any portal (menu, popover, toast) rendered outside the editor container, or it will open in the wrong room. > - **Must** check new text at 4.5:1 and marks at 3:1 in all five rooms and with Stronger contrast on. > - **Must** use the room's own mark swatches and timeline pairs for data colours inside the editor. > - **Never** change page geometry, type size or line breaks per room. > - **Never** add light, glow, gradient washes, vignettes or particles to a room. > - **Never** show a room's code id (`sepia`, `slate`) to a person. What a room may change: desk, chrome, page, ink, pencil, grain, card stock and rule, mark colours. What a room may never change: the page's geometry, the type, the page count, where a line breaks, what a mark means. **Do:** A scene card that takes `--k-surface` and `--k-text`, with its time-of-day mark from the room's swatches, checked in Paper and Midnight. **Don't:** A scene card with `background: #ffffff` and a saturated blue chip that looks right in Daylight and glares in Lamplight. **Do:** Mark the current scene with the 2px ring in the project's colour and the pointer above it. **Don't:** A glow, a brightness filter or rising particles on the current scene. **Do:** In a light room, talk in clay `#d9a58c` and action in sand `#dcd2bd`, dark ink on both. **Don't:** Plain pastels on white, saturated blocks with white numbers, or a sand mixed toward black until it turns brown. ## AI readiness test **Task:** Add a "Notes" rail to the screenplay editor that lists the writer's notes for the current scene. **Give the agent:** This page, Colour, the List row and Menu components, decision 0041. **Constraint:** It must sit correctly in all five rooms and with Stronger contrast on, and its ⋯ menu opens in a portal. **A reliable answer:** - Uses --k-surface, --k-text, --k-text-2 and --k-line only - Portal menu carries the editor's data-room - Text 4.5:1 and marks 3:1 in all five rooms - No glow, gradient or room-specific branches - Page geometry untouched --- # Spacing > Six steps from 4 to 32, two densities (a desk and a thumb), a 16px phone gutter, and the room a phone page keeps free at its foot. Source: https://kwark.space/designSystem/foundations/spacing ## Six steps Every gap, padding and margin in Kwark's interface is one of six values. A 4px base keeps type, icons and controls on the same grid; six steps are few enough that two people choosing a gap pick the same one. | Token | Value | Use | |---|---|---| | `--k-space-1` | 4px | Between a crumb and its separator (`--k-crumb-gap`), between an icon and a tight label in a chip, between a menu's edge and its first item | | `--k-space-2` | 8px | Between an icon and its word in a button (`TextButton`), between two buttons, between stacked floating items (the dial) | | `--k-space-3` | 12px | A row's inner gap, a chip's side padding, a menu item's side padding | | `--k-space-4` | 16px | The phone gutter, a card's padding, a sheet's side padding, the dial's distance from the screen edge | | `--k-space-5` | 24px | A dialog's padding, the gap between groups inside a card, the foot of a sheet above the home bar | | `--k-space-6` | 32px | Between sections of a page, an empty state's padding | **Proximity carries meaning.** Things that belong together sit closer than things that do not. A scene's title and its meta line are 2px apart; two scenes are a row apart; Act 1 and Act 2 are a section apart. If every gap is the same, nothing is grouped. **Off the scale, on purpose.** Three values outside the six are allowed, and only for these jobs: - **1px** lines and borders. - **2px** insets that exist for the [nested radius rule](https://kwark.space/designSystem/foundations/radius.md#corners-inside-corners): the segmented control's track padding, a title-to-meta gap in a row (`.k-row__text`). - **The paper's own geometry**: the screenplay page, the call sheet and the stripboard are measured in inches and lines, not in this scale ([Typography](https://kwark.space/designSystem/foundations/typography.md#the-screenplay-page)). > **For agents:** Use `--k-space-1` to `--k-space-6` for every gap, padding and margin in a component. Never write 10px, 14px, 18px or 20px. If a design seems to need one, take the step above or below and say which you chose. ## Two densities: a desk and a thumb The same control is smaller under a mouse than under a finger. Kwark has two sizes for every pressable thing and switches between them with the compact query (see [Layout](https://kwark.space/designSystem/foundations/layout.md)). | Thing | On a desk | Under a thumb (phone, sideways phone) | |---|---|---| | `IconButton`, `TextButton` | 32px | 44px (`--k-tap`) | | `Chip` | 32px | 44px | | Segmented choice | 30px inside a 2px track | 44px, and its word steps from 12 to 14px | | Breadcrumb item | 32px (`--k-crumb-height`) | No breadcrumb on a phone (Decision 0016) | | Dropdown menu item | 38px | 44px | | Phone menu row (`MenuSheet`) | — | 44px, 56px with a second line | | List row (`ListRow`) | 56px, 72px with a leading image | 56px; the whole row is the target | | Editor tool rail button | 34px in a 46px rail | No rail on a phone; its tools are in the ⋯ menu | The desk density is dense on purpose. Kwark is a working tool, and a writer on a laptop wants to see the scene list, the page and a panel at once. A 44px row on a desk wastes a third of the list. **Never** make a desk control smaller than 32px, and **never** make a thumb target smaller than 44 × 44px, even when the visible part is smaller (a 24px comment pin still has a 44px hit area). ## Phones: gutter, header, content, foot ```html
Outline Menu
Act 2 · 14 scenes
Scene 12
INT. EDIT SUITE – NIGHT
Scene 13
EXT. ROOFTOP – DAWN
Scene 14
INT. MIRA'S FLAT – DAY
--k-fab-slot
``` - **Gutter: 16px** (`--k-space-4`) on both sides. The production office uses `clamp(16px, 3.5vw, 40px)`, so it is 16 on a phone and grows to 40 on a wide desk. - **Header: one 44px line.** Back, a one-word title, the labelled Menu. Nothing else up there (Decision 0016). - **Content by y ≈ 200** on a 375 × 812 phone. Above the fold, the header plus at most one 40–48px band: a segmented control, one summary line, or one active filter (`docs/design-system.md`). Decision 0016 set the goal at y ≈ 120; on 18 October 2026 the Outline measured y ≈ 222 (it had been 392), with the act and view bar still to be folded into the header. - **The foot: `--k-fab-slot`.** Every phone page keeps `calc(78px + env(safe-area-inset-bottom))` free at its foot so the floating dial never sits on the last row. The 78px is the pen's 46px, 16px off the edge, and a 16px gap above. **Do:** Outline on a phone: one header line, one line that says *Act 2 · 14 scenes*, then the first card at about y = 100. The last card can scroll clear of the dial because the page keeps `--k-fab-slot` at its foot. **Don't:** A two-line header with the story name under the title, then a row of six chips, then a sentence explaining the view, so the first scene starts halfway down the screen and the last one sits under the dial. ## Inside components - A card's padding is `--k-space-4` on every side. A dialog's is `--k-space-5`. - Buttons in a row are `--k-space-2` apart, with the primary action last (on the right). - A form field's label sits `6px` above the input in the kit (`.kw-field`); in new work use `--k-space-2`. - Icon and word: `--k-space-2` in a button, `--k-space-1` in a chip. - A list has no gap between rows; rows are separated by a 1px line or by their own padding, never both. ## Known differences in the app - The dial in `components/ui/system.css` is 48px, while `--k-fab-slot` is reckoned for a 46px pen. The slot leaves 14px instead of 16 above it. The slot should be `calc(80px + env(safe-area-inset-bottom))` or the dial 46px. - The screenplay timeline and parts of the production office still use 9, 10, 11 and 14px gaps. They move to the scale when those files are touched. ## AI readiness test **Task:** Lay out the phone version of the Characters list: a header, a search field, and rows for Mira and eleven other characters. **Give the agent:** This page, Layout, Typography, the ListRow and PageHeader components. **Constraint:** The first row must start by y = 200 on a 375 x 812 screen, and the last row must not sit under the floating dial. **A reliable answer:** - One 44px header line with back, Characters, Menu - Search is the one band above the list, 44px tall - Rows are 56px with no buttons inside them - 16px side gutters - The list ends with --k-fab-slot of padding - Every gap is a --k-space token --- # Typography > Three faces with three jobs, six sizes, and a screenplay page measured against printed scripts down to the character. What to set, at what size, and what never to shrink. Source: https://kwark.space/designSystem/foundations/typography ## Three faces, three jobs Kwark uses one typeface for the interface, one for the titles of things, and one for the script. Each has one job, and a face never borrows another's. | Role | Token | Face | Weights loaded in the app | For | |---|---|---|---|---| | UI | `--k-font-ui` | Poppins | 300, 400, 500, 600 | Everything that is not below: body, rows, buttons, menus, fields | | Display | `--k-font-display` | Raleway | 400, 500, 600, 700, 800 | Page titles, section headings, row and card titles | | Screenplay | `--k-font-screenplay` | Courier Prime | 400, 700 | The script itself, and anything that quotes it as it prints | | Mono | `--k-font-mono` | The system monospace (SF Mono, Menlo) | System | Codes, take and slate numbers, timecodes, figures in tables | | Script in another language | `--k-font-script-*` | Courier Prime, then the script's Noto family | 400, 600 | Screenplay lines in Hindi, Tamil, Urdu, Japanese and 13 more scripts ([below](#other-scripts-in-the-screenplay)) | The weights are the ones `index.html` asks Google Fonts for. Poppins 700 is not loaded: a `font-weight: 700` on Poppins makes the browser fake a bold, which smears at small sizes. Use 600. **Why Poppins and Raleway.** Poppins is geometric and open at 12–14px, which is where most of the interface lives. Raleway is narrower and more literary at 16px and up; a scene's name set in Raleway reads as the name of something, not as a label. The pairing comes from the September 2026 stylesheets, which remain the reference for Kwark's look. **Why Courier Prime.** A screenplay is a printed artefact with a 100-year format, and its page count is how a production budgets and schedules. Every Courier is 0.6 em wide, so ten characters fill an inch at 12pt, and one page is about a minute of screen time. Courier Prime is the modern cut of that measure: same widths, better drawn. See [The screenplay page](#the-screenplay-page). > **For agents:** Set type with `font: var(--k-fs-*)/ var(--k-font-*)`. Never write a font name, and never write a `px` font size, in a component. Never set Poppins at 700; use 600. ## Six sizes | Token | Value | Name | Use | |---|---|---|---| | `--k-fs-hero` | clamp(36px, 4.5vw, 64px) | Hero | Landing and project hub, desktop only | | `--k-fs-display` | 28px | Display | Page titles on a phone, big numbers | | `--k-fs-head` | 20px | Heading | Section and page headings | | `--k-fs-title` | 16px | Title | Row and card titles | | `--k-fs-body` | 14px | Body | Body text and rows | | `--k-fs-meta` | 12px | Meta | Captions, meta lines, chips | | Size | Token | Weight | Line height | Use | |---|---|---|---|---| | 12 | `--k-fs-meta` | 400 for meta, 500 for chips and labels | 1.4 | Captions, meta lines under a row title, chips, field labels, hints | | 14 | `--k-fs-body` | 400 for reading, 500 for controls | 1.5 | Body text, rows, buttons, menu items, inputs | | 16 | `--k-fs-title` | Raleway 600 | 1.25 | Row titles, card titles, the phone header's one-word title, sheet titles | | 20 | `--k-fs-head` | Raleway 500 | 1.2 | Section and page headings on a desktop | | 28 | `--k-fs-display` | Raleway 600 | 1.15 | Page titles on a phone, big numbers | | 36–64 | `--k-fs-hero` | Raleway 700 | 1.05 | The landing page and the project hub on a desktop only. Never on a phone, never inside a module | There is no 13, 15 or 18. A design that seems to need one usually needs a different weight or colour at the size above or below. `--k-fs-hero` is a `clamp(36px, 4.5vw, 64px)`, so it grows with the window and never needs a phone override. **Do:** A scene row: *Scene 12* in Raleway 600 at 16px, then *INT. EDIT SUITE – NIGHT · 1 3/8 pages* in Poppins 400 at 12px in `--k-text-2`. Two sizes, two colours, one clear title. **Don't:** The same row in four sizes (15px title, 13px heading, 11px page count, 10px badge), so nothing is clearly the title and the smallest text cannot be read on a phone. ## Weights - **400** for anything read: body text, meta lines, the script. - **500** for anything pressed: buttons, menu items, chips, tabs, segmented choices. - **600** for titles: row and card titles, the phone header, dialog titles. - **700** only for Raleway at hero size, and for Courier Prime where a writer chose bold in the script. Never use weight alone to say a state (selected, unread, changed). Pair it with a mark, a colour step or a word, because a weight change of 100 is invisible to many readers. ## Line height and rhythm Body text runs at 1.5, which at 14px is a 21px line. Titles run tighter (1.25 at 16px; 1.2 at 20px) because they are one or two lines and need to hold together. Meta runs at 1.4. The screenplay is the exception and is never changed: 12pt type on 12pt leading, six lines to the inch, which on screen is 16px on 16px. Leading is the one typographic setting that moves the page count, so the editor treats any change to it as a change to the script's length and says so where it can be changed (`pagination/typeface.ts`). ## Measure Prose in the interface (a decision's explanation, a sheet's description, a long note) sits between 60 and 75 characters per line. The app uses `max-width: 70ch` most often for this; 64ch and 68ch also appear. - The script has its own measure, set by the format: 61 characters of action, 33 of dialogue, 28 of a parenthetical on US Letter. It is never re-flowed to fit a window. On a narrow window the page shrinks in proportion instead. - Tables and forms are not prose and do not take a measure; they take their columns. ## Numbers Columns of numbers line up. Use `font-variant-numeric: tabular-nums` wherever figures stack: the stripboard, the budget, the call sheet's times, the day out of days, page counts in a scene list. The production office does this throughout (`ProductionOffice.css`). - **Must** use tabular figures in any column, total or running timer. - **Must** use `--k-font-mono` for codes that are read character by character: slate and take numbers, timecodes, scene numbers like `12A`, invite codes. - **Never** use mono for prices or page counts in running text; they are words in a sentence there. - **Always** write eighths of a page the way a production does: `1 3/8`, not `1.375`. ## Truncation Truncate the chrome, never the work. - A row title, a header title or a breadcrumb item that runs out of room ends in an ellipsis on one line (`overflow: hidden; text-overflow: ellipsis; white-space: nowrap`), and its full text is available as the element's accessible name or a tooltip. - A card's summary may clamp at two lines (`-webkit-line-clamp: 2`, the app's most common clamp), three at most. - **Never** truncate the script, a character cue, a figure of money, a date, a call time, or anything a person is asked to confirm. If it does not fit, the layout is wrong. - **Never** truncate a button's word. `TextButton` never shrinks and never clips (`components/ui/system.css`); on the narrowest phones (below 360px) its padding gives way first. ## The screenplay page The page in the editor is the page that prints. It was measured against Highland Pro's own printed PDFs line by line in September 2026, and corrected again in Decision 0041 when a container rule moved cues and dialogue by a tenth of an inch. | | US Letter | A4 | |---|---|---| | Paper | 8.5 × 11 in | 8.27 × 11.69 in | | Margins (top, bottom, left, right) | 1, 0.75, 1.5, 0.9 in | 1, 0.75, 1.5, 0.67 in | | Lines per page | 55 | 60 | | Action and scene heading | 6.1 in, 61 characters | 6.1 in, 61 characters | | Dialogue | 1.0 in from the margin, 3.3 in wide, 33 characters | same | | Parenthetical | 1.6 in from the margin, 2.8 in wide, 28 characters | same | | Character cue | 2.2 in from the margin | same | A4 is a first-class paper, not an afterthought: it takes the narrower width out of the right margin, so the action measure stays 6.1 inches and an A4 script does not run long. The paper a script is set on is chosen once, at export, and the editor, the PDF and the schedule's eighths all count on it (`pagination/constants.ts`). On screen at 100%: the page is 816px wide (8.5 in at 96 to the inch), the head and foot margins are 96px, and each line is 16px. A typeface choice in the editor (Courier Prime, Courier New, DM Mono, or Noto Sans Mono with Devanagari) changes how the page looks, never how long it is, because all four set 0.6 em. Scene headings, character cues and transitions are capitalised because the format capitalises them. This is the only all-caps text in Kwark. ```html
INT. EDIT SUITE – NIGHT
Mira scrubs back through the take. Stops on a frame nobody else noticed: the actor looks at the lens.
MIRA
(quietly)
Play it again. Slower. I want to see when he decides.
CUT TO:
``` The demo sets the real indents in `ch`, which in a monospace face is one character: dialogue starts 10 characters in, the parenthetical 16, the cue 22, exactly as they do in inches at 12pt. > **For agents:** Never restyle the screenplay page with interface tokens. Its type is `--k-font-screenplay` at 12pt (16px at 100%) on 16px lines; its colours come from the room (`--k-page`, `--k-text`). Never change the indents, widths or lines per page in a component: they live in `pagination/constants.ts` and `pagination/typeface.ts`, and a change there must be re-checked against the Highland reference pages. ## Other scripts in the screenplay Filmmakers write whole screenplays in Hindi, Tamil, Urdu, Japanese or Spanish, or write action in English while characters speak another language, or switch mid-scene. Decision 0046 (accepted 16 November 2026) sets how the script's type follows the language. The menus and chrome stay in English; the script itself is set in its own script. How languages are chosen and typed is in [Writing systems](https://kwark.space/designSystem/foundations/writing-systems.md); the type is here. ### Script font roles Every script role starts with the screenplay face and falls back to a Noto family for the script. Latin letters, digits and punctuation inside a Hindi line stay in Courier Prime and keep their 0.6 em measure; only the characters Courier Prime lacks fall through to Noto. | Token | Falls back to | Set on `lang` | |---|---|---| | `--k-font-script-devanagari` | Noto Sans Devanagari | `hi`, `mr`, `ne`, `sa` | | `--k-font-script-bengali` | Noto Sans Bengali | `bn` | | `--k-font-script-tamil` | Noto Sans Tamil | `ta` | | `--k-font-script-telugu` | Noto Sans Telugu | `te` | | `--k-font-script-kannada` | Noto Sans Kannada | `kn` | | `--k-font-script-malayalam` | Noto Sans Malayalam | `ml` | | `--k-font-script-gujarati` | Noto Sans Gujarati | `gu` | | `--k-font-script-gurmukhi` | Noto Sans Gurmukhi | `pa` | | `--k-font-script-odia` | Noto Sans Oriya | `or` | | `--k-font-script-sinhala` | Noto Sans Sinhala | `si` | | `--k-font-script-urdu` | Noto Nastaliq Urdu, then Noto Sans Arabic | `ur`, with line height 1.9 | | `--k-font-script-arabic` | Noto Sans Arabic | `ar`, `fa` | | `--k-font-script-hebrew` | Noto Sans Hebrew | `he` | | `--k-font-script-jp` | Noto Sans JP | `ja` | | `--k-font-script-sc` | Noto Sans SC | `zh` | | `--k-font-script-kr` | Noto Sans KR | `ko` | | `--k-font-script-thai` | Noto Sans Thai | `th` | Each value is `var(--k-font-screenplay), '', sans-serif`, defined in the app's `styles/tokens.css`. The editor applies them by the block's `lang` attribute (`EditorModule/styles/scriptLanguage.css`), in the editor and in the print preview alike, so a speech marked Tamil is set in Tamil type wherever it is drawn. The Noto families load from Google Fonts with `unicode-range`, so a script written only in English downloads none of them. They are part of the app's token file. This site's `kwark.css` does not include them, because it does not load fonts; load the Noto family you need and use the token. ### What the type has to survive - **Measure.** Indian, Arabic and East Asian scripts have no monospace tradition. Their lines are measured as if they were Latin, so a line of Devanagari or Tamil may run a little long against the printed 33-character dialogue column; the editor says so where a typeface is chosen (`pagination/typeface.ts`). - **Height.** Vowel signs and conjuncts rise above and fall below the Latin line. Nastaliq is taller still, which is why Urdu gets a line height of 1.9. When a script with Indian-script lines prints, those lines are set at 0.9× so they clear the line above. - **Direction.** Urdu, Arabic, Persian and Hebrew blocks carry `dir="rtl"` and flow right to left (`unicode-bidi: plaintext`), while English lines beside them stay left to right. A right-to-left cue and parenthetical stay centred; a right-to-left transition sits at the left. - **Print.** The built-in PDF export (jsPDF) can only set Latin. A script with text it cannot set prints through the browser's Save as PDF from the export preview instead, so the text is shaped correctly; Decision 0046 widens this from the Indian scripts to every script outside the PDF's Latin set. The export dialog says what that copy leaves out (notes, alternates and translation appendices). ### Rules - **Must** set script text through `lang` on its block and let `--k-font-script-*` follow it. **Never** write a Noto family name in a component. - **Never** set an Indian, Arabic or East Asian script in Poppins or Raleway at 12px and assume it reads; check it at the size it will be used, on a phone. - **Never** letter-space, uppercase or synthesise bold on a string that may contain a non-Latin script. - **Never** let a script font change the page geometry: indents, widths and lines per page stay the format's. ## Type on phones - **Never** set anything under 12px on a phone, and nothing under 11px anywhere. - On a phone, controls that are 12px on a desk may step up to 14px (the segmented control does, `components/ui/system.css`), because a thumb needs a larger target and a larger word. - The phone header's title is one word at 16px Raleway 600. No subtitle under it (Decision 0016). - `--k-fs-hero` never appears on a phone; the largest type there is `--k-fs-display`, 28px. **Paper keeps its sizes.** The call sheet, the stripboard's strips, the day timeline's blocks and anything inside print rules are drawn at the size they print, because changing them changes what prints (Decision 0034). The 12px floor is for the interface around them. **Known debt.** A search of the app's source in November 2026 still finds around 600 lines that set 10px or 11px type, many of them in the screenplay timeline (9px and 10.5px labels). They are being moved to `--k-fs-meta` as each file is touched; do not copy them. ## Print - The script prints at 12pt Courier Prime on the chosen paper, with `@page` sized to it. - Interface chrome does not print: the floating dial and the editor's beat labels and ribbons hide under `@media print`. - Production paperwork prints at the sizes designed for paper; see [Print and export](https://kwark.space/designSystem/patterns/print-and-export.md). ## Writing in type - Sentence case everywhere: *Save scene*, *Call sheets*, *Prepare to shoot*. Not *Save Scene*. - No all-caps labels, and no letter-spaced small caps above sections. The app's phone menu still draws its group names in letter-spaced capitals (`.k-menu__group`); that is a known difference from this rule and is not a pattern to copy. - Italic is for titles of works and for a word the writer stressed. It is never a state. ## AI readiness test **Task:** Add a "Pages" column to the scene list that shows each scene's length, and a total at the foot. **Give the agent:** This page, Layout, the scene list's existing row markup. **Constraint:** No new font sizes or faces. The total must line up with the rows on a phone and a desktop. **A reliable answer:** - Lengths written in eighths (1 3/8), not decimals - font-variant-numeric tabular-nums on the column and the total - --k-fs-meta in --k-text-2 for row lengths, --k-fs-body 500 for the total - Nothing under 12px on a phone - Scene titles truncate with an ellipsis, the page count never does --- # UX writing > The micro-copy handbook. How Kwark words buttons, labels, errors, empty states, confirmations, toasts, notifications, first runs, settings and machine suggestions, with before and after tables from real Kwark strings and a word list. Source: https://kwark.space/designSystem/foundations/ux-writing ## How to use this page [Content](https://kwark.space/designSystem/foundations/content.md) sets the voice. This page is the working handbook: what to write in each kind of slot, with the strings Kwark already has. Every *Now* in the tables below is a real string from the app's source, found by searching `showToast(`, button labels and empty states. Where a string already works, it is listed as the model. Where it does not, the *Write* column is the fix, and the next person to touch that file should make it. Three tests for any string, in this order: 1. **Is it true?** Does it claim only what happened? *Saved on this device*, not *Saved*, when the cloud has not answered. 2. **Can the person act on it?** If something went wrong, does it say what to do next? 3. **Would we say it out loud to a nervous writer?** ## Buttons A button says what will happen, as a verb and its object, in sentence case. - **Verb first, object named**: *Issue call sheet*, *Retry saving*, *Copy invite*, *Make a restore point*. - **The same word through the flow.** The button that says *Issue* produces a toast that says *issued*. *Invite* leads to *Invited*. - **Bare verbs only where the object is obvious and universal**: *Cancel*, *Done*, *Close*, *Undo*. Kwark uses *Cancel* 58 times and *Done* 17; keep them. - **Never** *Submit*, *OK*, *Yes*, *No*, *Confirm* or *Click here*. They make the person reread the question. - **A destructive button names what it destroys**: *Delete draft*, *Remove Mira*. Never a bare *Delete* in a dialog. - **Opens something?** Add a chevron (*Menu ▾*) or an ellipsis in a menu item (*Room…*). | Now | Write | Why | |---|---|---| | *Let in* | Keep | Plain, specific, human | | *Retry saving* | Keep | Says exactly what it does | | *Sign in with Google* | Keep | Names the account it uses | | *Got it* (Reader guide) | *Hide this guide* | Says what happens; *Got it* asks the person to have understood | | *No* (day planner prompt) | *Keep my layout* | A bare *No* cannot be understood without rereading the question | | *Save* (generic, in a dialog) | *Save scene*, *Save location* | Names the object | ## Labels and fields - **A label is a noun phrase** above the field: *Crew call*, *Contingency %*, *What kind of thing*. - **Placeholders are examples, not labels**: `writer@studio.com`, *e.g. Police procedure*. If the field is empty and the label is missing, the person has nothing. - **Hints say what the field feeds**: the artefact it ends up in (Decision 0004), never a lesson. *Shown on the call sheet.* is a hint. *Think about what drives your character.* is coaching. - **Accessible names include the object**: *More for day 3*, *Add Zippo*, *Language for MIRA*, *Not a prop*. A screen reader user hears the name without the row around it. - **Units in the label**, not the field: *Contingency %*, *Length (min)*. ## Errors The structure, from Decision 0013: **what happened · that the work is safe, if true · what to do**. One or two sentences. No blame, no apology theatre, no exclamation marks, no codes. These are already right, and are the models: | String | What makes it work | |---|---| | *We could not reach the internet. Your work is safe on this device; try again when you are back online.* | State, safety, action | | *This change has not saved yet, so the page stays open. A copy is kept on this device.* | Explains why the page is still open | | *Could not switch drafts. Your current text is still open.* | Tells the writer nothing was lost | | *Could not keep a snapshot of your version, so nothing was replaced.* | Explains the safe outcome | | *Kept here, but it could not be saved yet.* | State first | | *The sign-in window was closed. Nothing changed; you can try again.* | No blame for closing it | | *You do not have access to this. Your work is safe; ask the project owner if you need it.* | Neutral, gives a route | | *Could not finish adding sub-acts. Retry to finish the same set without duplicates.* | Reassures about the retry | These need fixing: | Now | Write | Why | |---|---|---| | *Firebase is not configured.* | *This copy of Kwark cannot reach the cloud. Your work is safe on this device.* | Never name a vendor or a setup step | | *Invalid or expired reset link.* | *That link has expired or was already used. Ask for a new one.* | *Invalid* blames; give the action | | *Could not save that colour.* | *That colour was not saved. Your script is safe; try again.* | Add safety and the action | | *Could not prepare the pack.* | *The pack could not be made. Nothing in the project changed; try again.* | Say what was not affected | | *Could not save right now. Check the status banner.* | *Not saved yet. Your change is kept on this device and will go up when the cloud answers.* | Do not send the person looking elsewhere | | *Your change could not be saved. Please try again.* | *Your change was not saved yet. It is kept on this page; try again.* | Say where the work is | | *Could not import that CSV. Check the file structure and try again.* | *That file could not be read as a shot list. Check that the first row has column names, then try again.* | Say what *structure* means | | `Characters not in database: Mira, Selvi` | *Mira and Selvi are not in Characters yet. Add them?* | *Database* is not a place the writer knows | ## Empty states What goes here, how it gets here, and one way to begin. No jokes, no illustrations, no guilt. | String | Verdict | |---|---| | *No props yet. Tag them on the screenplay or in the Breakdown, or add one here.* | Model: names every route in | | *No scenes yet. The estimated runtime appears here as the script grows.* | Model: says what will appear | | *No cues yet, so nobody has spoken.* | Good: explains the cause | | *Nothing covered yet. Tick lines on the page to make a shot.* | Good: one action | | *Nothing by that name. Type a little more and you can add it yourself.* | Good: search that offers creation | | *No saved changes recorded here yet* (Your work) | Model: never says the person has not worked (Decision 0036) | | *No beats yet* (bare) | Add the route: *No beats yet. Open Writing to begin the story.*, as Kwark already says elsewhere | | *Add words…* (empty outline card) | Model: replaced coaching prompts (Decision 0004) | - **Never** write an empty state that implies failure (*You haven't written anything yet*). - **Never** put a question or a writing prompt in an empty field. ## Confirmations Prefer Undo to a question. Ask only when the action cannot be undone, or reaches other people. - **Title is the question with the object**: *Delete Draft 3?* - **Body says what is lost and what is kept**: *Its pages go. Your other drafts and the outline stay.* - **Buttons are the answer**: *Delete draft* and *Cancel*. Never *Yes* and *No*. | Now | Write | Why | |---|---|---| | *Are you sure you want to delete this draft?* | *Delete Draft 3?* · body: what goes · *Delete draft* | *Are you sure* doubts the person and tells them nothing | | *Are you sure you want to merge 4 rows? This action cannot be undone.* | *Merge 4 shots into one? This cannot be undone.* · *Merge shots* | Shorter, names the object | | *Are you sure you want to permanently delete this scene row?* | Move to trash with Undo instead; confirm only *Empty trash* | Recoverable actions do not need a question | | Delete shots with a confirm | *Deleted 3 shots.* with Undo | Undo is kinder and faster | ## Toasts A toast confirms what just happened, in the past tense, in one line, with an action only if the action is Undo or the obvious next step. | Now | Write | Why | |---|---|---| | *Rev 2 issued. Save it as PDF to send it to the crew.* | Keep | Says what happened and the next step | | *Mira is in, as Co-writer.* | Keep | Human, exact | | *12 dates added. Each can be changed or removed.* | Keep | Reassures that a machine-made batch is editable | | *Cover removed* with Undo | *Cover removed.* | Add the full stop; all toasts end with one | | *Entry moved successfully* | *Entry moved.* | *Successfully* adds nothing | | *Zoom optimized for sharing!* | *Zoom set for sharing.* | No exclamation marks | | *Auto-generated 12 shots* | *12 shots added, one for each scene without a shot. Each can be changed or removed.* | Says what was made and that the person is in control | | *Auto-linked Mira, Selvi* | *Linked Mira and Selvi to their cast.* | Name the result, not the mechanism | | *Dedicated mode applied: Coverage* | *Now using the Coverage layout.* | Plain words | | *Deleted property: Lens* | *Lens column removed.* with Undo | Name the thing as the person sees it | | `New Location "Kitchen" added to database` | *Kitchen added to Locations.* | No *database*; sentence case | - **Never** a toast for something the person can see happen. - **Never** a toast that disappears while it holds an Undo the person has focused. ## Notifications Kwark has no notifications that exist to bring people back, and it sends no email (Decision 0042). After inviting someone, the sharing panel offers *Copy invite* and *Email*, which opens the owner's own mail app. - A rule for anything built: a notification must be about something another person did that the recipient needs to act on (*Selvi asked to join Blank Pages*), never about the recipient's own activity, streaks or absence. - **Never** *We miss you*, *Keep your streak*, *You haven't written today*. ## First runs and onboarding No tours, no coaching, no quizzes (Decision 0004). The first run is the work itself, with the way to begin one step away. - **Say where the person is and what to do**: a heading and one primary action. - **Ask a question only if the answer changes something**, and make it skippable. Dailies asks *What do you do on a film?* once, multi-select, skippable, editable later, and the answer never changes anyone's access. - **Sign-in happens in place** and keeps any work made as a guest (Decision 0010). - **Sharing explains itself in one line**: *Sharing works through Google accounts, so only the people you add can open it.* ## Settings From the desktop-grade menus rule: anything chosen once and kept lives in Settings, labelled *This project* or *All your scripts*. Add only settings that change something. - **A setting is a label and a one-line effect.** *Stronger contrast. Fuller ink and firmer lines, in whichever room.* - **Say the privacy cost in the setting itself.** *Smart phonetic suggestions. Opt-in online dictionary suggestions while typing non-Latin words. Off by default: nothing you type leaves your device unless you enable this.* - **Name the scope**: this project, all your scripts, this device. - **Switches for things that stay on; radio items for one-of-several**, never a pile of checkboxes. ## Machine suggestions When Kwark offers something it worked out, the words must say where it came from, why, and that nothing happens until the person says yes. See [AI and authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md). The breakdown is the model: - Heading: *The script mentions* - Line under it: *Read off the page, never assumed. Nothing here counts until you say so.* - Each suggestion: the words from the page (*Zippo*), its category, and the reason in words a person can disagree with: *Anything an actor handles has to be there on the day.* or *Set in capitals, the way an element is introduced.* - Actions: *Add to the breakdown* (named *Add Zippo* for screen readers) and *Not needed* (named *Not a prop*). - Count: *Suggestions waiting*, never *Suggestions missed*. - **Never** *AI-powered*, *Smart* as a selling word, *magic*, sparkles, or a confidence percentage. - **Never** a suggestion about the quality of the writing. ## Word list | Use | Avoid | Why | |---|---|---| | Safe · Saved on this device | Synced, backed up (unless true) | Only what is true (0013) | | Not saved yet | Failed, error | Never *failed* (0013) | | Restore point | Snapshot, version, checkpoint | Decision 0015 | | Room | Theme, skin, mode | Decision 0015 | | Write · Prepare to shoot | Understanding, pre-production (as a label) | Decision 0009 | | Move to trash · Remove | Delete (when it can be recovered) | Say what really happens | | Delete | Remove (when it cannot be undone) | Say what really happens | | Issue (a call sheet) · Rev 2 | Publish, send, v2 | Kwark sends nothing; film's own word | | Reader · Co-writer · Director | Viewer, editor, admin | Film roles (0042) | | Person · writer · crew | User, member | Name the person | | Scene heading | Slug (in the interface) | Plain label; *slugline* is fine in docs | | Characters · Locations · Breakdown | Database, records, table | Places the person knows | | Add · Make | Create new, generate | Plain verbs | | Could not · do not | Unable to, invalid, illegal | Calm, clear for second-language readers | | Suggested · The script mentions | AI, smart, magic, auto- | Say the source, not the mechanism | | About 1 h 42 min | Exactly, precisely (for estimates) | Estimates are estimates | | Talk · Action | Talky, slow, weak | Measures, never judgement (0002) | | Ask the project owner | Contact your administrator | Kwark has owners, not admins | **Do:** *Scene moved to trash.* with Undo. **Don't:** A dialog asking *Are you sure you want to permanently delete this scene?* with *Yes* and *No*. **Do:** *That link has expired or was already used. Ask for a new one.* **Don't:** *Invalid or expired reset link.* **Do:** *The script mentions* · *Zippo* · *Anything an actor handles has to be there on the day.* · Add · Not needed **Don't:** *AI found 14 props* with a sparkle, already added to the breakdown. > **For agents:** - **Must** write buttons as verb plus object, in sentence case, and keep the same verb through the flow. > - **Must** write errors as what happened, that the work is safe if true, and what to do. > - **Must** write empty states as what goes here, how it arrives, and one way to begin. > - **Must** prefer Undo to a confirmation; confirm only what cannot be undone or reaches other people. > - **Must** give every machine suggestion its source, its reason and a way to say no. > - **Never** write *Submit*, *OK*, *Yes/No*, *failed*, *invalid*, *successfully*, *database*, *Firebase*, or an exclamation mark. > - **Always** check the word list before naming a new thing. ## AI readiness test **Task:** Write every string for a new "Merge two scenes" action in the scene navigator for Scene 12 and Scene 13. **Give the agent:** This page, Content, the Toast and Dialog components, the destructive actions pattern. **Constraint:** Merging can be undone from the script's history but changes scene numbers on an issued call sheet. **A reliable answer:** - Menu item "Merge with next scene" - Uses Undo for the merge, and a confirmation only because it reaches an issued call sheet - Dialog names both scenes and says Rev 2 will be out of date - Buttons "Merge scenes" and "Cancel" - Toast in the past tense with Undo, no exclamation mark --- # Writing systems > How Kwark writes a screenplay in more than one language and script: the four language modes, phonetic typing on an English keyboard, fonts per script, right-to-left lines, print and PDF limits, numerals, case and sorting. Source: https://kwark.space/designSystem/foundations/writing-systems ## Where Kwark stands A film's script is often in more than one language. Action and scene headings in English, a grandmother who speaks only Tamil, a hero who switches to Hindi when he is angry, an Urdu song. Kwark is built so a writer can type all of that on the keyboard they already have, keep the screenplay's format exact, and print it. There are two states to keep apart, and this page labels them: | | What it covers | Where | |---|---|---| | **Languages** | 31 screenplay languages in 19 script families (Decision 0046), including Hindi, Marathi, Bengali, Tamil, Telugu, Kannada, Malayalam, Urdu, Arabic, Japanese and Korean | kwark.space | | **How they are typed** | Four language modes, phonetic typing on an English keyboard with a candidate strip under the caret, per character or per line | kwark.space | | **How they are set and printed** | A Noto font role per script, right-to-left lines, and print routing for every complex script | kwark.space | Never tell a person a language is supported until it is on kwark.space. > **The interface stays in English.** Decision 0046 localises the screenplay, not the menus: translating the editor's chrome into every language was ruled out of scope, so menus stay calm and consistent. Write interface strings so they can be translated later (whole sentences, nothing stitched together, room to grow by half). ## The four language modes Decision 0046 stores a `scriptLanguage` setting on the project (`ScriptLanguageConfig` in `types/index.ts`), beside the per-character languages it already had (`scriptCastLanguages`). It offers two primary modes and four workflows, set in **Settings › Language**. | Mode | `mode` | What the writer sees in Settings | Who it is for | |---|---|---|---| | Whole film in one language | `single` | *Every scene heading, action line, cue, and speech is written in one language.* | A Tamil film written in Tamil | | Movie + dialogue split | `split` | *Write action, scenes, and cues in one language (e.g. English) and all dialogue in another (e.g. Hindi).* | The common Indian working script | | By character | `by-character` | *Write the movie in one base language and assign each character their own spoken language.* | A family drama in three languages | | Fluid | `fluid` | *Switch language on the fly at any line with the language pill or shortcut.* | Code-switching dialogue | How a line's language is decided (`resolveBlockLanguage()` in `utils/scriptLanguages.ts`), in order: 1. A language set on the line itself (`attrs.lang`) wins. 2. In `single`, everything is the film's language. 3. In the mixed modes, only spoken blocks (dialogue, parenthetical, lyrics) change. They take the speaking character's language if one is set; in `split`, otherwise the dialogue language. 4. Everything else (scene headings, action, cues, transitions) is the film's language. A project made before modes existed opens as `by-character` if it already had character languages, and `single` otherwise. Nothing a writer typed is reinterpreted. **Switching as you go.** In the screenplay's bottom bar, a language pill shows the language and mode the caret is writing in and opens a quick switcher. ⌥⌘L (Ctrl+Alt+L) opens it from the keyboard. On a speech, a small chip shows the line's script (*Aa* for English, the script's own mark otherwise) and sets the speaker's or the line's language; *Only this line* keeps the change to one line. ## Typing a script on an English keyboard Most Indian writers type Hindi the way they text it: *kya haal hai*. Kwark meets that habit. - The Roman word being typed shows in the line's script in a **candidate strip** just under the caret. - **Space**, a punctuation mark or **Enter** writes in the first candidate. - **↑ ↓** or a click picks another; candidates are numbered when there is more than one. - **Esc** keeps that word in Roman letters (a brand name, an English word in a Hindi line). - **Enter and Tab keep their screenplay meaning.** The word is written in first, then Enter moves to the next element. The phonetic scheme in the shipped build: a, aa or A, i, ii or ee or I, u, uu or oo or U, e, E or ae, ai, o, O, au; capitals for the retroflex T D N L and for R; sh, Sh, ch, chh, kh, gh, jh, th, dh, ph, bh; zh for ழ; M for the nasal dot, H for visarga; x for ksh. In the south a plain e and o are the short vowels. A Hindi word ending in *a* after a consonant is written with a long a, because *kya*, *tha* and *accha* are said that way. **Accuracy.** A fixed table writes *main* as मैन when the writer means मैं. Kwark fixes this with a curated lexicon of everyday dialogue words ranked first (मैं before मैन, में, है, हैं), then established open-source engines (`indic-transliterator`, `@indic-transliteration/sanscript`, `wanakana` for Japanese, `es-hangul` for Korean, `transliteration`), with `eld` for language detection. **Privacy.** Everything above runs on the device. Nothing the writer types leaves it. A separate switch, *Smart phonetic suggestions*, asks an online dictionary input service for better candidates; it is **off by default**, and Settings says so in plain words: nothing you type leaves your device unless you enable this. Results are normalised to NFC and the offline engines take over if the service does not answer. **The phone's own keyboard.** A writer using Gboard's Tamil keyboard or the macOS Hindi input is already typing the script. While the operating system's input method is composing, Kwark steps aside completely, so nothing is converted twice. **The strip never moves the page.** The candidate strip must be zero width in the line's flow, so it never moves a line or a page break while the writer types. Any change to the strip's styles must be checked against this rule before release: padding or a margin in the flow breaks it. > **For agents:** - **Must** keep phonetic typing and every candidate source on the device unless the writer has turned on *Smart phonetic suggestions*. > - **Must** let Esc keep a word in Roman letters, and never convert a word the writer kept. > - **Must** step aside while an operating-system input method is composing. > - **Never** let a typing aid change line breaks, page breaks or the page count. ## The 31 languages Decision 0046's list, grouped as the picker groups them. *Phonetic* means Roman letters on an English keyboard convert to the script. | Group | Languages | Script family | Phonetic | |---|---|---|---| | Common | English | Latin | no | | Indian | Hindi, Marathi, Nepali, Sanskrit | Devanagari | yes | | Indian | Bengali · Tamil · Telugu · Kannada · Malayalam · Gujarati · Punjabi · Odia · Sinhala | Their own scripts (Gurmukhi for Punjabi) | yes | | Indian | Urdu | Arabic, right to left | yes | | Middle East | Arabic, Persian | Arabic, right to left | yes | | Middle East | Hebrew | Hebrew, right to left | yes | | East and South-East Asia | Japanese · Chinese (Pinyin) · Korean | Japanese, Chinese, Korean | yes | | East and South-East Asia | Thai | Thai | no | | European | Spanish, French, German, Italian, Portuguese, Turkish | Latin | no | | European | Russian, Ukrainian | Cyrillic | yes | | European | Greek | Greek | yes | ### Screenplay conventions in other languages With *Localised scene prefixes & transitions* on (only offered in the whole-film mode, for a language other than English), the editor also recognises the film language's own conventions. English `INT.`, `EXT.`, `INT./EXT.` and `I/E.` are always recognised as well, so a script stays portable. | Language | Scene prefixes | A transition | Continued | |---|---|---|---| | Hindi | अं. · बा. · अंदर. · बाहर. | कट टू: | | | Tamil | உள். · வெளி. | கட் டு: | | | Urdu | اندر. · باہر. | کٹ ٹو: | جاری | | French | INT. · EXT. | COUPE À : | SUITE | | German | INNEN. · AUSSEN. | SCHNITT AUF: | FORTSETZUNG | | Korean | 실내. · 실외. · S# | 컷 투: | 계속 | French keeps its space before the colon (*COUPE À :*), as French typography does. Copy these from `utils/scriptLanguages.ts`; never translate a convention yourself. ## Fonts for each script Courier Prime has no Indian, Arabic or East Asian letters. Decision 0046 adds a font role per script family. Each keeps the screenplay face first, so Latin stays monospaced and on the grid, and lets Noto shape the script. | Token | Falls back to | Languages | |---|---|---| | `--k-font-script-devanagari` | Noto Sans Devanagari | Hindi, Marathi, Nepali, Sanskrit | | `--k-font-script-bengali` | Noto Sans Bengali | Bengali | | `--k-font-script-tamil` | Noto Sans Tamil | Tamil | | `--k-font-script-telugu` | Noto Sans Telugu | Telugu | | `--k-font-script-kannada` | Noto Sans Kannada | Kannada | | `--k-font-script-malayalam` | Noto Sans Malayalam | Malayalam | | `--k-font-script-gujarati` | Noto Sans Gujarati | Gujarati | | `--k-font-script-gurmukhi` | Noto Sans Gurmukhi | Punjabi | | `--k-font-script-odia` | Noto Sans Oriya | Odia | | `--k-font-script-sinhala` | Noto Sans Sinhala | Sinhala | | `--k-font-script-urdu` | Noto Nastaliq Urdu, then Noto Sans Arabic | Urdu | | `--k-font-script-arabic` | Noto Sans Arabic | Arabic, Persian | | `--k-font-script-hebrew` | Noto Sans Hebrew | Hebrew | | `--k-font-script-jp` · `-sc` · `-kr` | Noto Sans JP · SC · KR | Japanese, Chinese, Korean | | `--k-font-script-thai` | Noto Sans Thai | Thai | Every token is `var(--k-font-screenplay), 'Noto Sans …', sans-serif`. The editor picks one by the line's `lang` attribute, so a font is chosen by the language, never guessed from the text. Fonts load by Unicode range: a writer who never types Tamil never downloads it, which matters on a metered phone. On kwark.space, a writer can also set the whole script in *Noto Sans Mono + Devanagari*. The app is honest about its limit: *Devanagari has no monospace tradition, so lines of it are measured as Latin and may run a little long.* **Interface type.** Poppins, the interface face, draws Devanagari as well as Latin. Raleway, the display face, does not, so a project title in Hindi falls back to the device's font in headings. Any heading that can hold a person's own words must be checked with a Hindi and a Tamil title. ## Line height and the marks above and below Indian scripts stand taller than Latin: vowel signs (matras) sit above the headline and below the base, and conjuncts stack. Urdu's Nastaliq slopes and stacks further. - In print, Indian-script lines are set a tenth smaller than the Courier line, so their vowel signs clear the line above while the page keeps six lines to the inch. - Urdu lines take a line height of 1.9 on screen. - In the interface, any text that can hold a person's words keeps a line height of at least 1.5 and is never clipped: no `overflow: hidden` with a tight `height` on a title, a chip or a card. - **Truncate by grapheme, not by character.** Cutting क्ष after its first code point leaves a broken letter. Use `Intl.Segmenter` with `granularity: 'grapheme'`, or CSS `text-overflow: ellipsis` on a single line, never `slice()`. ## Page count A screenplay's page count rests on Courier: every character 0.6 em wide, ten to the inch at 12pt, six lines to the inch. Kwark measures Indian-script lines as if they were Latin, so a page heavy with Devanagari may run a little long. Say so where a writer reads the count of a non-Latin script; never present it as exact. ## Right to left Urdu, Arabic, Persian and Hebrew are written right to left. - **On kwark.space:** not supported. The editor does not set a direction per line. - Each block gets `lang` and `dir` (`rtl` for `ur`, `ar`, `fa`, `he`), `unicode-bidi: plaintext` so English words inside an Urdu line keep their own order, and right-aligned text. Cues and parentheticals stay centred; a right-to-left transition sits on the left. The print preview mirrors the same rules. - **The page itself stays left to right.** The screenplay's margins, scene numbers and page furniture are the format's, not the language's. Rules for anything else that shows a person's words: - **Must** use logical CSS properties (`margin-inline-start`, `padding-inline-end`, `text-align: start`) so a line can flip. - **Must** set `dir="auto"` on user text in lists, cards and titles. - **Never** mirror icons that are not directional (a clock, a camera). Mirror only arrows that mean back and forward. - The interface itself is not mirrored. A right-to-left interface is not planned. ## Bilingual scripts and the people who read them - **Translations.** Any dialogue line can carry a translation. It shows under the line, is set to the dialogue width, and can be printed as an appendix. - **Romanised lines.** An actor who speaks Hindi but does not read Devanagari can switch the Reader to show those lines in Roman letters, the way Hindi is written in a text message (*kya haal hai*), not a scholar's transliteration. The same switch works for the other scripts Kwark supports. - **Table reads.** A line is handed to a voice that can read it: romanised Hindi goes to a Hindi voice as Devanagari, and Devanagari handed to an English voice is romanised first. - **Spellcheck** is language-aware: it never flags a Tamil or Hindi word as an English typo. ## Print and PDF Kwark's built-in PDF writer (jsPDF with its standard Courier) can only print Western European Latin text, and it cannot shape Indian scripts (conjuncts, vowel signs that come before the consonant) even with a font embedded. So: | Script contains | Exported through | Notes | |---|---|---| | Only Latin in the Windows-1252 set (English, French, Spanish, German without ẞ) | jsPDF | Fast, selectable text | | Any Indian script (kwark.space) | The export preview's own pages, printed with the browser's *Save as PDF* | Text is real and correctly shaped. Notes, alternates and translation appendices are left out of that copy, and the export dialog says so | | Greek, Cyrillic, Hebrew, Arabic, Indian, Sinhala, Thai, Chinese, Japanese, Korean | The same browser route | Right-to-left lines print right to left | **Known gaps.** - Turkish `ş ğ ı İ` and German capital `ẞ` (in the `AUẞEN.` prefix) are outside both the Windows-1252 set and the routing check, so they would go to jsPDF and print wrongly. - The print face lists Noto for Devanagari, Arabic, Urdu, Tamil, Bengali, Japanese, Chinese and Korean only. Telugu, Kannada, Malayalam, Gujarati, Punjabi, Odia, Sinhala, Hebrew and Thai lines fall back to whatever font the device has. ## Case, numerals, dates and sorting **Capitals.** Scene headings, cues and transitions are capitalised by convention. Only scripts with case (Latin, Cyrillic, Greek) have capitals; Devanagari, Tamil, Arabic and Chinese do not, so a cue in Tamil is written as typed. Uppercase with the line's language: `toLocaleUpperCase('tr')` turns *iç* into *İÇ*, plain `toUpperCase()` gives the wrong *IÇ*. The current print code uses plain `toUpperCase()`; that is a known gap for Turkish. **Numerals.** Scene numbers (*12*, *12A*) and page numbers are written in Western digits in every language, because a crew's paperwork and a production's software match on them. A writer may type Devanagari digits (०–९) in their own text; Kwark keeps them as typed and romanises them for an actor. **Money and dates.** Money follows the currency's own people: ₹12,50,000 for rupees (`Intl.NumberFormat('en-IN')`). Dates follow the device's locale. For crews, write the weekday with the date. See [Content](https://kwark.space/designSystem/foundations/content.md). **Sorting.** Sort people's words with `localeCompare`, as the World view does (base sensitivity, numeric), so *Scene 2* comes before *Scene 10* and accents do not split a name. Some lists (the cast roster) still use a plain `localeCompare`; move them over when touched. Scene order is the script's order and is never alphabetical. **Search.** Compare text in NFC (the romaniser already normalises to NFC), so a word typed on one keyboard finds the same word typed on another. **Do:** Pick the font by the line's `lang` (`--k-font-script-tamil` for a Tamil line) and keep `var(--k-font-screenplay)` first. **Don't:** Guess the script from the characters, or set a whole script in one Noto face so Latin loses its monospaced grid. **Do:** Say that Indian-script scripts print through *Save as PDF*, and which appendices are left out. **Don't:** Embed a Noto font in jsPDF and call it done; the letters will be there and the words will be wrong. **Do:** Keep the interface in English and make the screenplay speak the writer's languages. **Don't:** Half-translate the menus, or put a language picker in front of a writer who only writes English. > **For agents:** - **Must** set `lang` (and `dir` where right to left) on every rendered line that has a language, on screen and in print. > - **Must** choose fonts through the `--k-font-script-*` role for the line's language, with the screenplay face first. > - **Must** route any text outside the Windows-1252 set to the browser print path, and say what that path leaves out. > - **Must** uppercase with the line's locale, and truncate by grapheme. > - **Must** name only languages that kwark.space supports today when telling a person what Kwark can do. > - **Never** send typed text to an online service unless *Smart phonetic suggestions* is on. > - **Never** let a language feature change the page's geometry or line breaks. ## AI readiness test **Task:** Add a "Character list" print sheet for Blank Pages that shows each character's name, spoken language and first scene. **Give the agent:** This page, decision 0046, utils/scriptLanguages.ts, Print and export. **Constraint:** Names may be in Tamil, Hindi or Urdu; the sheet must print correctly and keep the interface in English. **A reliable answer:** - Each name carries its lang and dir, and right-to-left names flow right to left - Fonts from --k-font-script-* with fallbacks - Any complex script prints through the browser print path, and the sheet says so - Sorted with localeCompare, scene numbers in Western digits - No text sent to an online service --- # Foundations > The decisions every Kwark screen is built on, from the six type sizes to the reason the editor never glows. Read these before you draw a component. Source: https://kwark.space/designSystem/foundations ## What a foundation is in Kwark A foundation is a decision that holds on every screen, in every module, on every device. Colour roles, the six type sizes, the four corner radii, the spacing steps, the layers things float on, how long motion lasts, which icon pack: these are not choices a module makes for itself. A module that chooses its own blue, its own 13px or its own 18px corner is a module that looks like a different product, and Kwark has seen that happen. The production office once had its own typeface; the call sheet once had its own buttons. Both were brought back into the building. Foundations live in two places at once: - **In the app:** `styles/tokens.css` in the Kwark repository holds every value, and `docs/design-system.md` states the rules. Checks in the build count violations per file and fail when a file gets worse. - **Here:** `kwark.css` (the same roles, framework-free) and `tokens.json`, so a person or an agent can build without the app's source. Where this site and the app disagree, this site says so on the page, and the app's value is the one that ships. ## The basics The eight pages a builder needs first. Each one is a click from anywhere on this site. - [Colour](https://kwark.space/designSystem/foundations/color.md): Colour in Kwark is a set of roles. Components ask for the page, the surface or the accent, and the theme, the room or the project decides what that is. - [Typography](https://kwark.space/designSystem/foundations/typography.md): Three faces with three jobs, six sizes, and a screenplay page measured against printed scripts down to the character. What to set, at what size, and what never to shrink. - [Radius](https://kwark.space/designSystem/foundations/radius.md): Four corners, each for one kind of thing, a rule for corners inside corners, and the paper that is never rounded more than paper is. - [Elevation](https://kwark.space/designSystem/foundations/elevation.md): Kwark is flat. Depth is a line and a step in tone; a shadow is only for something that floats above the page, and the layers it floats on are numbered once. - [Spacing](https://kwark.space/designSystem/foundations/spacing.md): Six steps from 4 to 32, two densities (a desk and a thumb), a 16px phone gutter, and the room a phone page keeps free at its foot. - [Layout](https://kwark.space/designSystem/foundations/layout.md): Where things go on a phone, a sideways phone, a tablet, a desk and a television, decided by one shared compact query, with the screenplay page at the centre of every one. - [Motion](https://kwark.space/designSystem/foundations/motion.md): Motion in Kwark answers something a person did, lasts 120 to 320 milliseconds, eases out, and stops when reduced motion is on. Nothing moves on its own. - [Iconography](https://kwark.space/designSystem/foundations/iconography.md): One icon pack, three sizes, one stroke, and a word beside almost every icon. Which glyph each Kwark module uses, which glyphs may stand alone, and what a chevron promises. ## How Kwark thinks The decisions behind the values: why Kwark is calm, how it treats a writer's work, and how it reads in other scripts and for other bodies. - [Design principles](https://kwark.space/designSystem/foundations/principles.md): The rules Kwark decides by, each with its reason, what it changes on screen, where it shows in the app and the trade-off it settles. - [Accessibility](https://kwark.space/designSystem/foundations/accessibility.md): WCAG 2.2 AA is the floor. This page gives Kwark's contrast per role, the keyboard map for the screenplay, timeline and boards, focus, screen readers, targets, motion, zoom, media and the checks every change must pass. - [Inclusive design](https://kwark.space/designSystem/foundations/inclusive-design.md): Who Kwark is for, what each of them stands to lose, and how Kwark decides on their behalf: students from 13, cheap phones on slow networks, offline work, many languages, calm for every kind of mind, privacy and cost. - [Writing rooms](https://kwark.space/designSystem/foundations/rooms.md): The screenplay editor's five rooms (Studio, Daylight, Paper, Lamplight, Midnight): what each is made of, how every colour in the editor is worked out from it, the legibility maths, and the rules for building inside one. - [Writing systems](https://kwark.space/designSystem/foundations/writing-systems.md): How Kwark writes a screenplay in more than one language and script: the four language modes, phonetic typing on an English keyboard, fonts per script, right-to-left lines, print and PDF limits, numerals, case and sorting. ## Words, machines and data How Kwark speaks, how it marks words a machine proposed, and how it draws numbers. - [Content](https://kwark.space/designSystem/foundations/content.md): Kwark's voice and tone: calm, plain and film-literate. How Kwark talks about saving and errors, the film words it uses and how, capitalisation, numbers, dates and times for crews, and names and roles. - [UX writing](https://kwark.space/designSystem/foundations/ux-writing.md): The micro-copy handbook. How Kwark words buttons, labels, errors, empty states, confirmations, toasts, notifications, first runs, settings and machine suggestions, with before and after tables from real Kwark strings and a word list. - [AI and authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md): Kwark's stance on machines and the writer's work. What a machine may and may not do in Kwark, how anything it proposes is marked, sourced, consented to and undone, what happens to the work's privacy, and why Kwark chose the margin mark over the industry's sparkles and glows. - [Data visualisation](https://kwark.space/designSystem/foundations/data-visualization.md): The charts Kwark draws (the timeline, the story spine, the stripboard, the calendar, Dailies, the budget's top sheet), the colours they use and in what order, labels over legends, accessible alternatives, and the one chart Kwark never draws: a score for the writing. ## Rules that hold across every foundation - **One value per job.** If two things look different but do the same job, one of them is wrong (`docs/design-system.md`, principle 1). - **The role, never the value.** A component asks for `--k-surface`, not `#ffffff`, and `--k-fs-body`, not `14px`. That is what lets the same row sit in light, dark and five writing rooms. - **The writer's choices are content, not UI.** The room a writer works in, the typeface of the Reader, a pitch deck's slide design: these may differ from the system, because the writer chose them. Everything around them is the system. - **Flat.** Depth is a line and a step in tone. Only things that float above the page carry a shadow ([Elevation](https://kwark.space/designSystem/foundations/elevation.md)). - **Phones first for the work.** On a phone the screen belongs to the writing: one header line, one floating button, content by about y = 200 (Decision 0016). > **For agents:** Before you write a component, read the eight basics. Use only `--k-*` tokens. If the value you need is not a token, stop and say which value and why; do not add one silently. Where this site notes that the app ships a different value, follow the app's value in app code and this site's value in `kwark.css` work, and say which you used. ## Where the values come from | Foundation | In the app | Here | |---|---|---| | Colour | `styles/tokens.css`, `utils/projectAccent.ts`, `EditorModule/utils/editorTheme.ts` | `--k-bg` … `--k-danger` | | Type | `styles/tokens.css`, `EditorModule/pagination/typeface.ts` | `--k-font-*`, `--k-fs-*` | | Radius | `styles/tokens.css` | `--k-radius-*` | | Elevation | `styles/tokens.css` (`--ds-z-*`), `components/ui/Modal.tsx` | `--k-z-*`, `--k-shadow-pop` | | Spacing | `styles/tokens.css` | `--k-space-1…6`, `--k-tap`, `--k-fab-slot` | | Layout | `EditorModule/hooks/useEditorLayout.ts`, `hooks/useBreakpoint.ts` | `COMPACT_QUERY` | | Motion | `components/ui/system.css`, `shared/SleekLoader.css` | `--k-dur-*`, `--k-ease` | | Icons | `components/ui/Icon.tsx` | `--k-icon-*` | ## AI readiness test **Task:** Build a new "Locations" summary card for the project overview that works on a phone and a desktop, in light and dark. **Give the agent:** This page and the eight basics it links to. **Constraint:** No new tokens, no new icon pack, no shadow on a resting card. **A reliable answer:** - Every value is a --k-* token - Card radius is --k-radius-card (10px) with a 1px --k-line border and no shadow - Title in --k-font-display at --k-fs-title, meta at --k-fs-meta - Lucide MapPin icon at 16px with the word Locations beside it - 44px tap target on a phone --- # Guides > Longer guides on the hardest problems in creative tools, written from the decisions behind Kwark. All are coming soon; this page gives each one's outline and who it is for. Source: https://kwark.space/designSystem/guides ## What the guides are The design system tells you what to do. The guides will tell you how Kwark arrived there: the problem, the options that lost and why, the details that only show up at real size, and how to carry the same thinking into your own product. Each is one subject, taken from first principles to working screens. They will be paid. None is available yet, and there is nothing to buy or sign up for on this page. When a guide is ready, it will be listed here and in [Releases](https://kwark.space/designSystem/releases.md). > Everything a team needs to build with the system stays free on this site: the foundations, components, patterns, kits, method and agent files. The guides go deeper on why; they never hold back a rule you need. ## Authorship-first AI for creative tools **Coming soon.** For product teams adding machine assistance to a writing, editing, storyboard or music tool, and for the designers who have to decide what the machine may touch. Most AI features in creative tools are designed from what the model can do. This guide starts from who the author is. 1. Why a creative tool is different: the work is the person's, and so is the credit. 2. Suggest, never write: the revision mark, and why every machine word stays marked until a person accepts it. 3. What a machine must never do: score, grade, give coverage, or rank a person's story (Decision 0002), and how to say no to that feature when it is requested. 4. Accept, edit, refuse: interaction design for each, on desktop and phone, by keyboard. 5. Provenance: showing where a suggestion came from (the person's own outline, research, an earlier draft). 6. Exports for the person's own AI, kept secondary. 7. Copy for machine features that does not oversell. 8. A review checklist and readiness tests for any AI feature. ## Designing timelines and playheads **Coming soon.** For designers and engineers building editors, audio tools, animatics, schedules or anything with time on one axis. 1. What a timeline is for in each craft: the cut, the mix, the animatic, the shoot schedule. 2. The playhead: position, scrubbing, snapping, and the keyboard model (J, K, L and frame steps). 3. Density at real size: a feature-length cut, two hundred strips, a scene with no dialogue. 4. Colour for data on a timeline: light-room pastels taken a step deeper, never saturated blocks. 5. The phone: a resting strip, and a full edit bay when the phone turns sideways (Decision 0007). 6. Accessibility: a timeline a screen reader can navigate, and markers that have names. 7. Performance budgets for scrubbing and redraws. 8. Printing time: the stripboard and the cue sheet. ## Indic and bilingual interfaces **Coming soon.** For teams shipping to India or to any audience that writes in more than one script, and for anyone whose product holds people's own words. 1. Scripts are not fonts: shaping, conjuncts, vowel signs and why some PDF libraries cannot print them. 2. Type sizes and line heights that keep Indian scripts readable beside Latin text. 3. Bilingual work: dialogue in two languages, transliteration and translation as separate things. 4. Input: typing in an Indian script on a laptop and on a phone. 5. Print and export that keeps the text correct, and the trade-offs between routes. 6. Interface language and content language are different settings. 7. Testing with real writers' text, not sample strings. ## Design systems for two readers **Coming soon.** For design-system teams who want their system to be followed by coding agents as reliably as by people. 1. Why agents drift to generic defaults, and what stops them. 2. One source, two outputs: pages and markdown twins from the same file. 3. Writing rules an agent can follow: Must, Never and Always, exact names, no interpretation. 4. The machine files: AGENTS.md, llms.txt, tokens, a component manifest, and what each is for. 5. An MCP server and skills: when they help and when a single file is enough. 6. Readiness tests: writing them, running them in fresh conversations, grading without scores. 7. Keeping it true: generated files, enforcement tests and versioning. ## Paper and digital as one act **Coming soon.** For teams building production software: breakdowns, stripboards, call sheets, shot lists, budgets. 1. The paper artefacts film crews already trust, and why a table beside them is not enough. 2. Issuing: locking a call sheet, numbered revisions, and what changes after issue (Decision 0020). 3. Designing for the clipboard and the phone at the same time. 4. Page geometry measured from industry documents. 5. Sharing by film role: who sees and edits what (Decision 0042). 6. Country differences: unions, contracts and paperwork are not one country's. ## Calm saving, sync and offline **Coming soon.** For anyone whose product holds work people cannot afford to lose. 1. The fear: what a writer thinks when a sync word changes. 2. One word per state, and which states fade (Decision 0013). 3. Offline first: what is kept on the device, and saying so honestly. 4. Conflicts: two sessions, two copies, and a choice that never loses either. 5. Undo instead of "Are you sure?", recoverable trash, and named versions. 6. Error copy that says the work is safe, when it is. 7. Testing interruption: closing the tab halfway, losing signal on set. ## AI readiness test **Task:** A reader asks whether they can buy the timelines guide today and what it covers. **Give the agent:** This page. **Constraint:** Only what this page says. No prices, dates or sign-up offers. **A reliable answer:** - Says the guide is coming soon and not available yet - Summarises its outline accurately - Says who it is for - Says the free system pages hold every rule needed to build - Does not invent a price, date or mailing list --- # Any creative app > Carry Kwark's approach into another craft, such as music, animation, theatre, comics, games or podcasts, without importing film-specific assumptions: find the craft's own paper, its own units and its own conventions, then build them as one act. Source: https://kwark.space/designSystem/kits/any-creative-app ## Who it is for Teams building tools for any craft where a person makes something of their own: songwriting and music production, animation, theatre and stage management, comics, game narrative, podcasts, choreography, architecture sketchbooks. The other kits are about film. This one is about how to take Kwark's way of working into a craft it was not designed for. ## The method, in five steps ### 1. Find the craft's paper Every craft has a physical artefact its people already trust: the screenplay page, the stripboard, the call sheet, the index card. Music has the lead sheet and the chord chart; theatre has the prompt book and the rehearsal report; animation has the exposure sheet (X-sheet); comics have the thumbnail and the script page; podcasts have the run sheet. Find it before drawing a screen, and build the screen as that artefact (Decision 0005: paper and digital together). The structured data is what the paper already holds. ### 2. Find the craft's units Film counts pages in eighths and time in `HH:MM:SS:FF`. Other crafts count differently: bars and beats at a tempo; frames on twos (animation drawn every second frame at 24 fps); cues and scenes; panels and pages; spreads; minutes and segments. Use the craft's own unit everywhere, label it, and never convert it into a unit the craft does not use. ### 3. Find who owns each fact One document owns each fact. In theatre the script owns lines, the stage manager's prompt book owns cues, the rehearsal report owns what changed today. Bind every control to the owner, and carry facts forward rather than retyping them (the breakdown writes the sheet; the cast list feeds the call sheet). ### 4. Decide what a machine may do Measure, find, carry and convert; never judge or put words, notes or frames into the work without the person choosing them (Decision 0002). Read [AI and authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md). ### 5. Build the phone for the moment the craft uses it Film's phone moments are the recce, the set at 6 a.m. and the train ride home with the script. Find your craft's: the rehearsal room, the gig, the studio between takes. Design the phone for that moment, content first (Decision 0016). ## Mapping Kwark's components to other crafts | Kwark component | Music | Theatre | Animation | Comics | Podcasts | |---|---|---|---|---|---| | [Screenplay page](https://kwark.space/designSystem/components/screenplay-page.md) | Lyric sheet | Prompt book page | Script | Script page | Script, run sheet | | [Index card](https://kwark.space/designSystem/components/index-card.md) | Section (verse, chorus) | Scene or French scene | Sequence | Page or panel beat | Segment | | [Story spine](https://kwark.space/designSystem/components/story-spine.md) | Song structure | Acts | Sequences | Issue structure | Episode rundown | | [Script timeline](https://kwark.space/designSystem/components/script-timeline.md) | Arrangement in bars | Running time | Edit length in frames | Page count | Running time | | [Stripboard strip](https://kwark.space/designSystem/components/stripboard-strip.md) | Session plan | Rehearsal schedule | Production schedule by shot | Page schedule | Recording schedule | | [Call sheet](https://kwark.space/designSystem/components/call-sheet.md) | Session sheet | Rehearsal call | Daily assignments | Not used | Recording call | | [Storyboard frame](https://kwark.space/designSystem/components/storyboard-frame.md) | Not used | Blocking sketch | Storyboard, layout | Thumbnail | Not used | | [Waveform](https://kwark.space/designSystem/components/waveform.md) | Tracks | Sound cues | Dialogue track for lip sync | Not used | Tracks | | [Script revision diff](https://kwark.space/designSystem/components/script-revision-diff.md) | Arrangement changes | Script changes in rehearsal | Script changes | Script changes | Edits | ## Live demo The same components, used for a song: sections as cards on the paper, a structure strip, and a session plan in rows. ```html
Track 3 · Section 3

Verse 2: the drive home

Strip the drums back to brushes.

1:42Bars 33–48
Session plan, Saturday
TimeTrackPartsPlayers
10:003 · Drive homeDrums, bassRavi, Ana
13:303 · Drive homeVocalMira
``` ## Conventions you must look up, not invent The system's rule for every kit is that domain conventions are stated accurately or not at all. When you apply Kwark to a new craft: - **Must** find the craft's own standards from its practitioners, unions, guilds or standards bodies, and cite them in your decision record. For example: tempo and time signature in music notation; the X-sheet's frame columns in animation; the stage manager's cue naming (often LX for lighting and SQ or Sound for sound cues in UK practice, with numbering conventions that differ by company); comics script formats that differ by publisher. - **Never** present one company's habit as an industry standard. Where practice varies, say *conventions vary* and make it a setting. - **Always** ask two or three practitioners before building a multi-screen flow, then walk the journey and get the UX agreed (memory: UX before build; few questions, then decide and build). ## Keyboard map Start from Kwark's shared map and add the craft's own transport and element keys. | Key | Does everywhere | |---|---| | ⌘ S | Says *Saved*; saving is continuous | | ⌘ Z / ⇧ ⌘ Z | Undo / redo | | ⌘ F | Find | | ⌘ K | [Command palette](https://kwark.space/designSystem/components/command-palette.md) | | Esc | Close the open menu, sheet or panel and return focus | | Space, J, K, L | Transport, wherever there is time | | ? | Keyboard shortcuts | Menus are desktop-grade with five at the top level where possible (Decision 0015) and shortcuts shown in items. Read [Menus and shortcuts](https://kwark.space/designSystem/patterns/menus-and-shortcuts.md). ## Phone and desktop - **Phone:** one 44px header line (back, a one-word title, at most two labelled actions, *Menu ▾*), content by about y = 200, one floating control, menus as sheets that drill down one page at a time (Decision 0016). Read [Phones](https://kwark.space/designSystem/patterns/phones.md). - **Desktop:** the craft's paper at its true geometry, panels beside it, keyboard first. ## AI and authorship The rules are the same in every craft: - **Never** score, grade, rank or judge the work or the artist (Decision 0002). No "song strength", no "panel composition score", no streaks. - **Never** save machine-made words, notes, frames or values into the work. Mark them with the [Revision mark](https://kwark.space/designSystem/components/revision-mark.md) and a source until the person accepts or edits them. - **May** measure, find, carry and convert. Say what ran, where, and on what data. - **Never** send the work to a model provider by default. Private is the default (Decision 0001); every outward step is chosen, explained and reversible. - **Never** imitate a real artist's voice, likeness or style on request without their documented consent. ## Before you ship - The craft's paper prints, and the printout matches the screen. - Every unit is labelled. - Nothing judges the work. - The phone layout works at 320px and 375px. - A decision record explains each convention you adopted and its source (see [Decision records](https://kwark.space/designSystem/method/decision-records.md)). ## Edge cases to test - A person works in a way the craft's convention does not describe: structure stays optional (Decision 0003), and nothing breaks when the expected sections are missing. - Work is written in an Indian script or right to left: units, numbers and layout follow [Writing systems](https://kwark.space/designSystem/foundations/writing-systems.md). - The craft's paper is wider than a phone: the phone shows a reading view with the paper's proportions kept, not a shrunken page. - Two people edit the same artefact: presence is shown ([Presence cursor](https://kwark.space/designSystem/components/presence-cursor.md)) and conflicts are resolved in the calm voice of [Saving and sync](https://kwark.space/designSystem/patterns/saving-and-sync.md). - The person deletes something by mistake: Undo in a toast, not a confirmation dialog ([Destructive actions](https://kwark.space/designSystem/patterns/destructive-actions.md)). ## Starter prompt > You are adapting the Kwark Design System to a new craft: {craft}. Read https://kwark.space/designSystem/kits/any-creative-app.md, /foundations/principles.md, /foundations/ai-and-authorship.md and /patterns/phones.md. First list the craft's paper artefact, its units, who owns each fact, and the phone moment, and mark every convention you are unsure of as "to confirm with practitioners" instead of inventing it. Then map the craft's screens to existing Kwark components using the mapping table. Use only `--k-*` tokens. Do not add any feature that judges the work or saves machine-made content without the person's acceptance. ## AI readiness test **Task:** Plan a rehearsal tool for a theatre stage manager using the Kwark Design System. **Give the agent:** Any creative app kit, Screenplay page, Call sheet, Script revision diff, Phones pattern. **Constraint:** Cue naming differs between companies. **A reliable answer:** - Names the prompt book as the craft's paper - Uses the company's own cue naming as a setting, not a claimed standard - Rehearsal calls reuse the call sheet pattern with numbered revisions - Script changes in rehearsal tracked with the revision diff - Phone designed for the rehearsal room - Nothing judges the performance --- # Colour grading > Build a grading or dailies colour tool on Kwark: a neutral viewer with before and after, scopes that measure, primaries with numbers, a node graph that shows order, clips with versions, and looks named by their colour spaces. Source: https://kwark.space/designSystem/kits/colour-grading ## The workspace Clip 04 of Scene 12 (12B-1, Mira's close-up) on version v3, *Night, warmer skin*. The viewer splits original and graded; the scopes measure the graded frame; the strip shows the scene's clips with the DP's grade note above them; the node graph shows the order (balance, contrast, a skin key and a monitor window in parallel, then the show look); the primaries hold the numbers. ```html
Blank PagesScene 12 · clip 04
Saved
ViewerClip 04 · 12B-1
Original · no gradeGraded · v3
01:04:17:10Rec.709 · gamma 2.4 · this screen is not a grading reference
ScopesClip 04 · after node 05 · 10-bit video range
WaveformLuma
Vectorscope75% targets · 2×

CursorColumn 412 of 1920Luma 598 · 56%R 662G 571B 498

ClipsScene 12 · 8 clips · 5 graded

Scene 12 grade note Keep the monitor cool and Mira’s skin warm. Night, not blue. DP · 14 Nov

  1. 01v201:04:00:00Graded
  2. 02v301:04:06:12Graded
  3. 03v201:04:12:18Graded
  4. 04v301:04:17:00Graded
  5. 05v101:04:24:14Graded
  6. 06—01:04:29:02Not graded
  7. 07—01:04:33:00Not graded
  8. 08—01:04:38:10Not graded
Clip 04 versions
NodesClip 04 · 12B-1 · version v3
InOut
01Balance
02Contrast
03KeySkin
04WindowMonitor
+
05LUTNight look v3
PrimariesClip 04 · node 01 Balance
Lift
Y −0.012R −0.020G +0.004B +0.031
Gamma
Y +0.006R −0.006G +0.004B +0.012
Gain
Y 1.020R 1.040G 1.012B 0.962
Offset
Y 0.000R +0.003G 0.000B −0.002
``` Shown dark, as grading rooms are. Scopes and the picture stay black in every theme; the panels around them follow the theme. Under 640px the workspace becomes the phone approval view: compare, versions, the note. ## Components in this kit - [Compare viewer](https://kwark.space/designSystem/components/compare-viewer.md): Before and after on one frame: a split line you drag, labels on both sides, Split, Wipe, Side by side or Toggle, and a plain statement of the viewing transform and that this screen is not a reference. - [Video scopes](https://kwark.space/designSystem/components/video-scopes.md): Waveform, RGB parade, vectorscope with 75% targets and the skin-tone line, and an RGB histogram, on black, with labelled scales, legal-range lines and a cursor read-out in code values. - [Colour wheels](https://kwark.space/designSystem/components/colour-wheels.md): Primary correction: lift, gamma, gain and offset as four wheels with a hue ring, a puck, a master slider and Y R G B read-outs, under one row of contrast, pivot, saturation, temperature and tint. - [Colour curves](https://kwark.space/designSystem/components/colour-curves.md): Custom curves with Y, R, G and B channels over a histogram, and hue-versus-saturation with its hue band: a plot with a grid, control points, and the input and output of the selected point in numbers. - [Node graph](https://kwark.space/designSystem/components/node-graph.md): The order of operations in a grade: numbered nodes with a picture of their result, serial and parallel paths, a mixer, key and window badges, and the selected node outlined. - [Clips and grade versions](https://kwark.space/designSystem/components/grade-clip-strip.md): The grading timeline as pictures: numbered clips with timecode, Graded or Not graded in words, the version in use, the scene's grade note, and the clip's versions including a machine suggestion that is never applied on its own. - [Looks and LUTs](https://kwark.space/designSystem/components/look-picker.md): Choose a show look or a conversion LUT by its before-and-after on the actual frame, each named with source, destination, size and format; the Look Book's references sit alongside and apply nothing. - [Video player](https://kwark.space/designSystem/components/video-player.md): A viewer: picture on a neutral black surround, safe-area guides, burnt-in timecode and slate, a scrub bar with the in–out range, and the compact transport. **Ready for Kwark.** Kwark has no grading module. Its founder finishes films in DaVinci Resolve, and Kwark's Camera & Light workspace already records the camera, recording format, EI and white balance a grade starts from. These components are for a grading or dailies tool built on the system. ## Layout | Region | Holds | Rules | |---|---|---| | Viewer | The image through the output transform, compare modes | The largest panel; neutral black surround | | Scopes | Waveform, parade, vectorscope, histogram | Beside the viewer, never under a panel that moves | | Clips | The scene in edit order, versions, the grade note | Full width; scrolls sideways | | Nodes | Order of operations | Pans; never scales text below 11px | | Primaries and curves | The numbers of the selected node | Under the viewer, nearest the hands | On a wide screen (from 1100px): viewer and nodes on top, clips across, primaries and scopes below. Narrower: viewer and scopes, then clips, nodes, primaries, each at its natural size. ## The surround is part of the measurement - Nothing coloured near the picture: Kwark's accent, project colours and the coral playhead stay out of the viewer's frame. Panels are neutral greys in both themes. - The viewer says what it shows: *Rec.709 · gamma 2.4*. On an uncalibrated screen it says *this screen is not a grading reference*, and review links always do. - Overlays only when turned on (safe areas, false colour with its legend). ## Density | Thing | Size | |---|---| | Panel header | 28px | | Number fields | 22px, three decimals, true minus | | Wheel | up to 132px, four across from 560px | | Scope labels | 11px figures, 12px letters | | Clip thumbnails | 128px at 16:9 | ## Colour spaces, LUTs and exchange - Name both **gamut** and **transfer function**: *Rec.709 (BT.709) with BT.1886 gamma 2.4*, *DCI-P3 gamma 2.6*, *Rec.2020 PQ (ST 2084)*, *Rec.2020 HLG*, *ACEScct*. Camera log is vendor-specific (*ARRI LogC3 · AWG3*, *S-Log3 · S-Gamut3.Cine*, *Log3G10 · REDWideGamutRGB*); read it from metadata and let people correct it. - A LUT's name says **source, destination, purpose, version and size**: *Blank Pages · Night v3 · LogC3 → Rec.709 · 33-point · .cube*. Show looks and conversion LUTs live in separate lists. - The **ASC CDL** (slope, offset, power, saturation) carries a primary grade between apps and from set to suite. - Scopes say their range: 10-bit **video (legal)** 64–940 or **full** 0–1023; HDR scopes read in nits. ## Keyboard | Key | Does | |---|---| | Space, J, K, L | Play and shuttle | | ↑ / ↓ | Previous / next clip | | ⌘ D | Bypass the grade (one key, always) | | ⌘ ⇧ D | Bypass all grades | | G | Grab still | | W | Wipe against the selected still | | ⌥ S / ⌥ P | Add serial / parallel node | | ⌥ ↑ / ⌥ ↓ | Previous / next version | | ⌘ C / ⌘ V | Copy / paste a grade to selected clips | | ⌥ 1–4, ⌥ 0 | One scope large, four up | ## Kwark's angle - **The scene carries the brief.** The DP's grade note for Scene 12 (*keep the monitor cool and Mira's skin warm; night, not blue*) sits above its clips. - **The Look Book is the reference.** Its images appear beside the LUTs and in the compare viewer's wipe; they apply nothing. - **Versions are never overwritten.** A change makes the next version; a machine suggestion is a new version with a revision mark. ## Accessibility for colour-critical work - Never encode a state only in a hue: *Graded* and *Not graded* are words; channels are R, G, B letters with a dot, never coloured text. - Every scope has a numeric read-out at the cursor, so traces are not the only way in. - Every wheel and curve point is a slider with value text in numbers; everything the puck shows, the read-outs say. - People with colour vision differences grade professionally by scopes and numbers; the interface must work entirely by them. - Reduced motion: wipes and version changes cut instead of animating. ## Phones **Makes sense on a phone:** a director or DP comparing *Graded* and *Original*, choosing between versions, leaving a note at a frame, reading the scene's grade note. The view says *Colours on this screen are approximate*. **Does not:** grading. Wheels, curves, nodes and scopes need a calibrated display and a stable signal. Under 640px the workspace shows only the compare viewer and the clips with their versions. ## AI and authorship - **May** suggest a shot match to a still, a starting balance, a tracked window on a face, or read camera metadata. Each produces a new, marked version, never an edit to the current one. - **Never** apply a look to the whole timeline without the colourist choosing it. **Never** rate an image as well or badly graded (Decision 0002). - The camera original is never altered; grades are metadata on top of it. **Do:** *v4 Suggested match to still 3*, dashed and marked, beside the colourist's versions. **Don't:** *Auto look applied to 214 clips.* ## Starter prompt > You are building a dailies grading workspace on the Kwark Design System. Read https://kwark.space/designSystem/kits/colour-grading.md and the components it links: Compare viewer, Video scopes, Colour wheels, Colour curves, Node graph, Clips and grade versions, Looks and LUTs. Use `kw-pro` classes and `--k-pro-*`, `--k-scope-*`, `--k-hue-*` tokens; scopes and picture on black in every theme. Name gamut and transfer function everywhere; name LUTs by source, destination, purpose, version and size; keep looks and conversion LUTs apart. Show numbers for every control. Keep every version; machine suggestions are new marked versions. Report anything the system does not define. ## AI readiness test **Task:** Build the DIT's on-set look tool for day 8. **Give the agent:** Colour grading kit, Compare viewer, Video scopes, Colour wheels, Looks and LUTs, Node graph. **Constraint:** ARRI LogC3 camera, Rec.709 monitors, CDL to the colourist; a director approves on a phone. **A reliable answer:** - Three nodes in order (input, CDL, show LUT) - Wheels with numeric read-outs exported as CDL - Scopes labelled 10-bit video range - LUTs named with spaces and size - Compare original and graded with labels - Phone view compares and notes only and says colours are approximate --- # Editing > Build a picture editor or review tool on Kwark: a bin that knows the script, source and program viewers, a multitrack timeline with one coral playhead, timecode written correctly, and the keyboard editors already use. Source: https://kwark.space/designSystem/kits/editing ## The workspace Scene 12 of *Blank Pages*, cut v4, the way an editor sees it: the day 7 bin on the left, **Source** (12B-4, Mira's close-up, in its camera clock) and **Program** (the cut at 01:04:10:07, the active viewer) above, and the timeline below with the in–out range around 12B-1, a 12-frame dissolve, the out point being trimmed and snapped to the A1 edit, and a marker that points at a line of the screenplay. Every part is a component on its own page. ```html
Blank PagesScene 12 · cut v4
Saved
Scene 12Day 7 dailies · 7 clips
NameTakeStartDurationCamScript line
12A-1114:18:02:1100:00:41:08AReel 3 loops on the monitor.
12A-3In cut314:19:40:0300:00:44:20AReel 3 loops on the monitor.
12B-1In cut114:22:27:0000:00:38:02A“Who put you there?”
12B-2214:24:11:0700:00:12:15A“Who put you there?”Boom in frame
12B-4In cut414:27:50:1800:00:39:11A“I didn’t shoot this.”
12C-2In cut214:41:05:1200:00:22:00BSelvi on the monitor.
12D-1Media offline114:52:13:0400:00:30:09B“Run it from the beginning.”
Source12B-4 · Mira CU
12B-4 · A003C01914:27:58:02
14:27:58:0200:00:03:14
ProgramScene 12 · cut v4
12B-1 · A003C01201:04:10:07
01:04:10:0700:00:06:06
In → out00:00:06:06
V2VFX
12C-2 · Screen comp v2
V1Picture
12A-3 · Wide
12B-1 · Mira CU
12C-2 · Monitor insert
12B-4 · Mira CU
A1DX Mira
12A-3 · Boom
12B-1 · Lav Mira
12B-4 · Lav Mira
A2DX Selvi
12C-2 · Monitor playback+2
A3BG Room
BG · Edit suite room tone
A4MX Score
1M3 · Reel theme
``` The workspace is shown in the dark theme, where editors work. Each component follows the theme and works in light; switch any component's demo to Light. Under 640px wide the same workspace becomes the phone review: the program viewer and the cut, nothing to edit. ## Components in this kit - [Timecode display](https://kwark.space/designSystem/components/timecode.md): The clock of picture and sound: HH:MM:SS:FF in Poppins tabular figures, labelled with which clock it is and its frame rate, with a semicolon for drop-frame and typed relative entry. - [Transport bar](https://kwark.space/designSystem/components/transport-bar.md): Mark in and out, step, play backwards and forwards, loop, marker and match frame, in one 32px row; with the J/K/L shuttle gauge that shows speed and direction. - [Video player](https://kwark.space/designSystem/components/video-player.md): A viewer: picture on a neutral black surround, safe-area guides, burnt-in timecode and slate, a scrub bar with the in–out range, and the compact transport. - [Source and program viewers](https://kwark.space/designSystem/components/viewer-pair.md): Two viewers side by side: the clip on the left in its own clock, the sequence on the right; one is active at a time, and the edit buttons sit between them. - [Edit timeline](https://kwark.space/designSystem/components/edit-timeline.md): The multitrack sequence: ruler in timecode, V2/V1/A1–A4 with patch, target, lock, mute and solo, clips named by slate with picture and waveforms, dissolve, trim handle, snapping, script-linked markers and one playhead. - [Bin](https://kwark.space/designSystem/components/bin.md): The media browser: clips by scene and day in a dense list with take, start timecode, duration, camera and the script line, or as picture thumbnails; circled takes and offline media marked in words. - [Clip inspector](https://kwark.space/designSystem/components/clip-inspector.md): Properties of the selected clip in dense rows: scrubbable numbers with units, a keyframe diamond per row, reset per section, and the slate and script line the clip came from. - [Marker list](https://kwark.space/designSystem/components/marker-list.md): Every marker in the sequence by timecode, with colour and number, duration, the note or the screenplay line it points to, and who left it. - [Playhead and scrubber](https://kwark.space/designSystem/components/playhead.md): One shared position in time: a coral pentagon head on a timecode ruler and a 1px line through every track, with the in–out range, the shuttle speed while playing and the time under it while scrubbing. - [Waveform](https://kwark.space/designSystem/components/waveform.md): Audio as amplitude against time: a mono dialogue clip with a dB scale, selection, playhead and clipped peaks marked, and a stereo pair below; the file's format and the clips named in words. **Ready for Kwark.** Kwark has no picture editor. It has what an edit grows from: the [Script timeline](https://kwark.space/designSystem/components/script-timeline.md) and its phone bay (Decision 0007), the animatic step of the Shot module, [Storyboard frames](https://kwark.space/designSystem/components/storyboard-frame.md) and dailies. These components are designed for an editor or review tool built on the system. ## Layout | Region | Holds | Width at 1440 | Rules | |---|---|---|---| | App bar | File, Edit, View, Tools, Help (Decision 0015), project and scene, Edit · Colour · Sound, *Saved* | full, 34px | One line; the save state in words | | Bin | Clips by scene and day | 22–28% | Scrolls inside itself; never pushes the viewers | | Source viewer | One clip in its clock | equal to Program | Shows *No clip loaded* on black when empty | | Program viewer | The sequence | equal to Source | The active viewer has the coral line | | Timeline | The sequence in tracks | full | At least 40% of the height on a laptop | | Inspector | Selected clip | 280–340px, right, optional | Opens over the bin's column, not the viewers | - Panels sit on a 2px well (`--k-pro-well`). No cards, no shadows, no rounded panels inside the workspace: square edges, one 10px radius around the whole window. - Every divider can be dragged; double-click returns it to the default. The layout is saved per person, not per project. - Viewers keep 16:9 (or the sequence's aspect) and letterbox on black; they never crop to fill. ## Density Editors look at this screen for ten hours. Density is a feature, legibility is the limit. | Thing | Size | |---|---| | Panel header, toolbar | 28px, 32px | | Bin and list rows | 26px | | Track height | V1 50px, V2 30px, audio 36px, small audio 30px | | Words | 12px Poppins (never smaller) | | Figures (timecode, scales) | 11px minimum, Poppins tabular figures | | Timecode in a toolbar | 14px; in a display 20px | | Lines | 1px; selection 1.5px; playhead 1px coral | ## Timecode - **`HH:MM:SS:FF`** with colons for non-drop-frame. Name the clock: *Program*, *Source · 12B-1*, *In → out*. - **Drop-frame** at 29.97 and 59.94 skips frame *numbers* 00 and 01 each minute except every tenth. Written with a semicolon: `00:01:00;02`. Never at 23.976, 24, 25, 30 or 50. - **Source** and **program** timecode are different clocks; never convert one into the other silently. - Many productions start a programme at **01:00:00:00**; make it a sequence setting. - Offer 23.976, 24, 25, 29.97, 30, 50, 59.94 and 60; keep the exact rational value (24000/1001) underneath. - Typed entry works anywhere: digits go to an absolute time, **+** or **−** to a relative one (`+212` is 2 s 12 f later). ## Editing operations - **Three-point editing**: two of the four points plus a third; the app works out the fourth. The bar between the viewers states it before the edit lands. - **Insert** pushes later material down; **Overwrite** replaces. Words, not glyphs. - **Trims**: ripple (one side, later clips move), roll (an edit point between two clips), slip (contents of a clip), slide (a clip between neighbours). Ripple moves everything after it, so the trim handle shows the frame count and the snap. - **Sync**: linked picture and sound that drift show the offset in frames on the clip (*+2*), in red, in words. - **Interchange**: EDL (CMX 3600), XML, AAF for sound turnover, OTIO. At least one round trip is the floor. ## Keyboard | Key | Does | |---|---| | Space | Play / pause | | J, K, L | Backwards, stop, forwards; repeat J or L for 2×, 4×, 8× | | ← / → | One frame; ⇧ for one second | | ↑ / ↓ | Previous / next edit | | I / O, ⌥ I / ⌥ O | Mark in / out, clear | | ⇧ I / ⇧ O | Go to in / out | | , / . | Insert / overwrite | | Q | Switch active viewer | | F | Match frame | | A, T, B | Select, trim, blade | | [ / ] | Trim one frame (⇧ ten) | | N | Snapping | | M | Marker at the playhead | | + / − / ⇧ Z | Zoom in, out, fit | | ⌘ Z / ⇧ ⌘ Z | Undo / redo | Show every shortcut in its menu item and tooltip. Never take single letters while a text field has focus. ## Kwark's angle - **The bin knows the script.** Clips carry scene, shot, take, circled takes and the line they cover, from the slate and the script supervisor's notes. Search finds *“Who put you there?”*. - **Markers can point at the screenplay.** *Scene 12, page 14* opens the line; cutting the line from the script keeps the marker and says so. - **One colour per character** across the film: Mira's dialogue tracks are coral in the timeline, the mixer and the ADR list. - **Nothing judges the cut.** No pacing scores, no "best take" (Decision 0002). ## Accessibility for picture work - Every viewer and track state is written as well as coloured: target, lock, mute, solo, sync offset, *Media offline*. - The playhead and scrubbers are sliders with timecode value text; nothing announces during playback, the position is announced on stop. - Every control reaches 3:1 against its panel; the coral playhead is deepened in light (`--k-pro-playhead`) to stay above 3:1 on white. - Captions are a first-class track and export with review copies. - Reduced motion: playback still plays; the timeline pages instead of scrolling. ## Phones **Makes sense on a phone:** watching a cut, reading timecode, leaving a note at a frame (*Note at this frame* stores the timecode), approving a version, seeing the marker list. Turned sideways, the picture fills the screen (Decision 0007). **Does not:** trimming, three-point editing, bins, track patching. A thumb cannot hit a frame, and accidental edits on a bus are the worst kind. Under 640px the workspace above shows only the program viewer and the cut, with frame back, play and frame forward as 44px buttons; track toggles become read-only marks. ## AI and authorship - **May** transcribe dialogue so it can be searched, match takes to script lines, detect shot changes, align a table read to the script. Each is a finding with its source. - **Never** make editorial choices silently: no automatic selects, no take ranking, no auto-cut saved into a sequence. A machine assembly may exist only as a separate, labelled sequence. - Anything machine-made in a sequence carries a [Revision mark](https://kwark.space/designSystem/components/revision-mark.md) until a person accepts it. **Do:** *Transcript ready · 41 lines matched to Scene 12*, each match openable and removable. **Don't:** *Auto-selected the best take* with the other takes hidden. ## Starter prompt > You are building the editing workspace of a picture editor on the Kwark Design System. Read https://kwark.space/designSystem/kits/editing.md and the component pages it links: Timecode display, Transport bar, Video player, Source and program viewers, Edit timeline, Bin, Clip inspector, Marker list. Use the `kw-pro` classes and `--k-pro-*` tokens; dark theme first. Keep one playhead position shared by every view, coral, never the project accent. Write time as HH:MM:SS:FF with the clock named and the frame rate shown; semicolon only for 29.97/59.94 drop-frame. Name clips by slate. Implement the keyboard map. Nothing under 11px for figures or 12px for words. No automatic selects or rankings. Say what you could not find instead of inventing it. ## AI readiness test **Task:** Build the assembly workspace for Scene 12 from the circled takes of day 7. **Give the agent:** Editing kit, Bin, Source and program viewers, Edit timeline, Marker list. **Constraint:** 24 fps sequence starting at 01:00:00:00; two cameras; phones review only. **A reliable answer:** - Bin with slate, circled takes and script lines - Source and program each with its own labelled clock - Timeline V1 plus dialogue tracks named by character - One coral playhead shared by every view - J/K/L, I/O, comma and full stop work - Under 640px only program and the cut, no editing --- # Production office > Build the producer's and line producer's tools on Kwark: a marked-up breakdown that writes its own sheets, cast and locations that feed the budget, paperwork that remembers when it was checked, and sharing by film role. Source: https://kwark.space/designSystem/kits/production-office ## Who it is for Teams building breakdown, budgeting, casting, locations and paperwork tools: the production office of a film. The people using it are producers and line producers, production managers and coordinators, ADs breaking down the script, casting directors, location managers, accountants, and heads of department checking their lists. This kit is in Kwark's pre-production, which is grouped in three bands by how tightly each module is bound to the screenplay (memory: pre-production in three bands). Components: [Breakdown page](https://kwark.space/designSystem/components/breakdown-page.md), [Element tag](https://kwark.space/designSystem/components/element-tag.md), [Cast board](https://kwark.space/designSystem/components/cast-board.md), [Location card](https://kwark.space/designSystem/components/location-card.md), [Budget top sheet](https://kwark.space/designSystem/components/budget-top-sheet.md), [Data table](https://kwark.space/designSystem/components/data-table.md), [Description list](https://kwark.space/designSystem/components/description-list.md), [Stat](https://kwark.space/designSystem/components/stat.md), [Board column](https://kwark.space/designSystem/components/board-column.md) for department requests. ## The screens | Screen | What it does | Components | |---|---|---| | Breakdown | Mark each scene's elements on the page; the sheet writes itself | [Breakdown page](https://kwark.space/designSystem/components/breakdown-page.md), [Element tag](https://kwark.space/designSystem/components/element-tag.md) | | Breakdown sheets | One per scene, with counts by department | [Breakdown page](https://kwark.space/designSystem/components/breakdown-page.md) (sheet row) | | Elements | Every element in the film, by department, with its scenes | [Data table](https://kwark.space/designSystem/components/data-table.md), [Element tag](https://kwark.space/designSystem/components/element-tag.md) | | Cast & Crew | Parts from the script, candidates by stage; crew list | [Cast board](https://kwark.space/designSystem/components/cast-board.md) | | Locations | Candidates for each scripted place, from idea to locked | [Location card](https://kwark.space/designSystem/components/location-card.md) | | Budget | Top sheet and accounts; lines follow cast and location rates | [Budget top sheet](https://kwark.space/designSystem/components/budget-top-sheet.md) | | Paperwork | Permits, releases and insurance, each with when it was last checked | [Data table](https://kwark.space/designSystem/components/data-table.md), [Description list](https://kwark.space/designSystem/components/description-list.md) | | Department desks | What each department needs, asked and answered | [Board column](https://kwark.space/designSystem/components/board-column.md), [Media grid](https://kwark.space/designSystem/components/media-grid.md) | | Sharing | People by film role, with dates | [Sharing and roles](https://kwark.space/designSystem/patterns/sharing-and-roles.md) | ## Live demo The sheet row for Scene 12, a cast part opened, a locked location and the top sheet. ```html
12INT. EDIT SUITE – NIGHT1 3/8 pages · MiraCast 1Props 2Effects 1

Top sheet · INR

Above the line18,40,000
Production31,25,000
Post-production9,80,000
Total59,45,000
``` ## Domain conventions ### Breakdown - A breakdown reads each scene for everything production must provide: cast, background (extras, junior artists), props, wardrobe, hair and make-up, vehicles, set dressing, special effects, visual effects, sound, music, stunts, animals and special equipment. Kwark's standard list adds mechanical effects, greenery, livestock, animal handlers, security, additional labour and miscellaneous; projects add their own. - Traditionally an AD underlines elements in coloured pencil, one colour per department, then copies them to a sheet per scene. There is no single universal colour key; software and productions differ. Kwark keeps each department's colour fixed across the app, chosen so no department reads as another (breakdown.css). Always print a legend. - A **breakdown sheet** heads with the scene number, INT/EXT, set, D/N and length in eighths, then lists elements by department. - Elements are named in the script's words. "Police car" is one vehicle, not two marks. ### Budget - A budget is organised into **accounts** (and lines within them), summarised on a **top sheet** read by producers and financiers. - **Above the line** covers story and rights, producers, director and principal cast; **below the line** covers production, post-production and other costs. Account numbering differs by country and by the budgeting software a financier expects; let the production choose a chart of accounts rather than inventing one. - Money in the project's currency, with that currency's grouping (Indian grouping 59,45,000 for INR). - A line may **follow a rate** from Cast & Crew or Locations, read live and named in words, with *I type the rate* to unlink (Decision 0022). A figure copied twice will drift. ### Casting Parts come from the screenplay; no role can be invented in casting (CastingBoard). Stages in Kwark: Idea, Approached, Read, Callback, Offer out, Cast, Passed. Fees and agents' details are behind Cast & Crew permission. ### Locations Each scripted place (EDIT SUITE) has candidates: Idea, Recce, Shortlist, Locked, Dropped. One locked location per place. Dropped candidates keep their reason. ### Paperwork Permits, releases, insurance and labour paperwork are **country-specific and change** (memory: understanding is about the story). Kwark records a person-typed *last checked* date and *what you were told*, and shows the age in words in grey (*Checked 12 days ago*). The app never decides a legal fact is out of date (Decision 0022). ### Sharing by film role Share by the role people hold on a film: Reader, Actor, Co-writer, Director, Producer, Camera, Crew, or Custom, with an optional end date (Decision 0042). A role is a template over a per-module map. Never default to *edit everything*. ## Keyboard map | Key | Does | |---|---| | Select text, then Enter | Open "is a…" to mark it on the breakdown page | | 1 – 9 | In that panel, choose the category in list order | | Esc | Close the panel without marking | | ← / → (scene list) | Previous / next scene | | ⌘ F | Find an element across the script | | ⌘ ↵ | In the budget, add a line under the current account | | ⌘ P | Print the current sheet | ## Phone and desktop **Desktop** is where breakdowns and budgets are built: the marked page beside the sheet, accounts beside the top sheet. **Phone** is for the recce and approvals: - Locations: photograph a candidate and add it to the scripted place on the spot. - Cast: move a candidate's stage after a call. - Budget: read the top sheet; edit nothing larger than a note. - Rows have no buttons on phones; actions are in the row's ⋯ sheet. ## AI and authorship Kwark's breakdown already guesses, with rules on the device: it reads capitals and a short list of nouns production must account for, and offers them under *The script mentions*, each with *Add* and *Not needed*. Nothing counts until a person says so ([AI and authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md)). - **May** find elements in the script and propose them, with the reason (*Set in capitals, the way an element is introduced*). - **May** propose lines for the budget from confirmed cast and locked locations (*Bring in 3 cast and location lines*). - **Never** add an element, a budget line or a cast decision without a person accepting it. - **Never** judge a budget as too high or too low, or a location as better. - **Never** move a fee into a place a wider role can read. **Do:** *The script mentions: Zippo · Prop* with Add and Not needed. **Don't:** Twenty props added to the sheet automatically because the model "found" them. ## Accessibility notes for this craft - Category names appear in words wherever colour does; printed sheets carry the legend. - Marking works from the keyboard. - Money is right-aligned in tabular figures; the currency is in the heading, not every cell. ## Edge cases to test - A line in the script is rewritten after it was marked: its marks disappear from the page and the sheet keeps the element with a note that the words are no longer in the scene, so nothing is lost silently. - The same prop appears in 40 scenes: *Mark it in all 40 scenes that mention it* does it in one act, and undo removes all 40. - A confirmed actor's fee changes in Cast & Crew: every budget line that follows it updates, and the top sheet shows the new total with the line's source named. - Two candidates are locked for the same scripted place by two people at once: the later lock wins, the earlier returns to Shortlist, and both people are told in words. - A paperwork item was last checked a year ago: the age shows in grey words, never in red, and no warning is raised by the app. - A collaborator's access ends on a date: their role stops at midnight in the project's time zone, and their own private research stays theirs. ## Starter prompt > You are building the breakdown and budget of a production office app on the Kwark Design System. Read https://kwark.space/designSystem/kits/production-office.md, /components/breakdown-page.md, /components/element-tag.md, /components/budget-top-sheet.md and /components/cast-board.md. Marking words on the read-only page must write the scene's sheet in the same act; offer marking every scene that mentions the same words. Budget lines may follow live rates from cast and locations and must say where a rate comes from. Paperwork records when it was last checked and never marks anything out of date by itself. Share by film role. Use only `--k-*` tokens. Report anything the system does not define. ## AI readiness test **Task:** Bring confirmed cast and locked locations into the budget for Blank Pages. **Give the agent:** Production office kit, Budget top sheet, Cast board, Location card, Decision 0022. **Constraint:** Only the producer can see actors' fees. **A reliable answer:** - Offers "Bring in N lines" for confirmed cast and locked locations only - Lines follow live rates with the source in words - No fee copied where a wider role can read it - Top sheet totals update - Nothing added without the producer accepting --- # Scheduling and call sheets > Build the first AD's tools: a stripboard in pages and eighths with the four paper colours, shooting days, day out of days, and call sheets issued as numbered, frozen revisions that print, save as PDF and download as CSV. Source: https://kwark.space/designSystem/kits/scheduling-and-call-sheets ## Who it is for Teams building scheduling and AD software, crew call apps, or the production side of a filmmaking suite. The people using it are first and second assistant directors, who build and break the schedule; production coordinators, who issue the sheets; heads of department, who read them the night before; and actors and crew, who hold the sheet on a phone at 6 a.m. This kit is in Kwark: Schedule (the stripboard), Call sheets (with issued revisions, Decision 0020), and the Calendar (Decision 0043). Components: [Stripboard strip](https://kwark.space/designSystem/components/stripboard-strip.md), [Call sheet](https://kwark.space/designSystem/components/call-sheet.md), [Production calendar](https://kwark.space/designSystem/components/production-calendar.md), [Production timeline](https://kwark.space/designSystem/components/production-timeline.md), [Data table](https://kwark.space/designSystem/components/data-table.md) for the one-liner and day out of days, [Element tag](https://kwark.space/designSystem/components/element-tag.md), [Stat](https://kwark.space/designSystem/components/stat.md). ## The screens | Screen | What it does | Components | |---|---|---| | Stripboard | Scenes as strips, ordered into days | [Stripboard strip](https://kwark.space/designSystem/components/stripboard-strip.md) | | Unscheduled tray | Strips not yet on a day | [Stripboard strip](https://kwark.space/designSystem/components/stripboard-strip.md) | | One-liner | The schedule as a dense printable list | [Data table](https://kwark.space/designSystem/components/data-table.md) | | Day out of days | Each cast member's working days by code | [Data table](https://kwark.space/designSystem/components/data-table.md) (dense) | | Calendar | The days on a calendar with prep, recces and deadlines | [Production calendar](https://kwark.space/designSystem/components/production-calendar.md) | | Call sheet | The day's sheet, working draft and issued revisions | [Call sheet](https://kwark.space/designSystem/components/call-sheet.md) | | Crew calls | Department call times | [Data table](https://kwark.space/designSystem/components/data-table.md), [Time picker](https://kwark.space/designSystem/components/time-picker.md) | | Issue | Freeze a revision; PDF and CSV | [Dialog](https://kwark.space/designSystem/components/dialog.md), [Toast](https://kwark.space/designSystem/components/toast.md) | ## Live demo A day on the stripboard, ending with its banner, and the day's call sheet as issued. ```html
Day4Thu 21 Nov · Lumen Studios3 scenes · 4 6/8 pages · cast 1, 2
12INTEdit suiteMira finds the frameN1 3/81
3INTLab corridorThe courier arrivesD5/812
14EXTStreet outside the labRain, the scooter leavesN2 6/82
End of Day 4 · 4 6/8 pages
Thea Experience

Blank Pages

DirectorMira RaoProducerDev M.1st ADSana K.
Crew call07:30Day 4 of 18Rev 3

Scenes

ScSet and descriptionD/NPagesCast
12Int. Edit suiteMira finds the frameN1 3/81
14Ext. Street outside the labRain, the scooter leavesN2 6/82
``` ## Domain conventions ### Page lengths in eighths Scenes are measured in **pages and eighths of a page**, as printed in standard screenplay format: *5/8*, *1 3/8*, *2*. One eighth is about an inch of the page. No scene is shorter than 1/8. Write lengths as whole pages and eighths, never as decimals (*1 3/8*, not *1.375*), and add them the same way (*4 6/8*). Kwark's `formatEighths` writes them exactly so. ### Strips - A strip carries the scene number, INT or EXT, the set (as in the slugline), D or N, the length in eighths, and the cast ID numbers in the scene. - **Paper colours** follow a common convention: white for interior day, yellow for exterior day, blue for interior night, green for exterior night. Productions and software vary (some add colours for dawn, dusk or second unit); Kwark keeps these four and says so. Colours are read from the scene heading. - **Day breaks** end each shooting day with a banner (*End of Day 4 · 4 6/8 pages*). Off days, travel days and holidays are their own banners. ### Cast ID numbers Each speaking part gets a number, conventionally by billing or prominence, with the lead as 1. The same number appears on strips, the call sheet and the day out of days. Never renumber cast once the schedule has gone out. ### Day out of days A grid of cast (or other elements) against shooting days, with a code for each day. Common codes: | Code | Means | |---|---| | SW | Start work: first day | | W | Work | | WF | Work finish: last day | | SWF | Start, work and finish on the same day | | H | Hold: paid but not working | | T | Travel | | R | Rehearsal | | F | Fitting | | Drop, pick up | Released, then brought back later, where an agreement allows it. Software writes these codes differently | Codes and drop/pick-up rules depend on the union or agreement and on the scheduling software; let the production configure them and print a legend. ### Call sheet The day's sheet carries, at least: production and company; the day (*Day 4 of 18*) and date; **crew call**, prominent; shooting call; breakfast and lunch times; sunrise and sunset; weather; scenes with set, D/N, pages and cast; cast with pick-up, make-up and wardrobe, and on-set times; locations with unit base, parking and directions; the **nearest hospital**; department notes; and an advance schedule for the next day. Personal phone numbers are scoped by role. ### Turnaround and hours Rest between wrap and the next call, meal breaks and maximum hours are set by law, union agreements or the production's contracts, and vary by country. Never hard-code a number; let the production enter its rules and show the gap in words when a call breaks one (*10 h since yesterday's wrap*). ### Revisions Issue numbered, frozen revisions per day (Decision 0020). The crew must be able to answer "which version did I get?". Script page revisions use the colour sequence instead; see [Script revision diff](https://kwark.space/designSystem/components/script-revision-diff.md). ## Keyboard map | Key | Does | |---|---| | ↑ / ↓ | Previous / next strip | | ⌘ ↑ / ⌘ ↓ | Move the strip up / down | | ⌘ ⇧ ↑ / ⌘ ⇧ ↓ | Move the strip to the previous / next day | | B | Insert a day break after the selected strip | | U | Send the strip back to Unscheduled | | Enter | Open the scene | | ⌘ P | Print the viewed call sheet revision | | C, T, W, M, A, L | Calendar: quick add, today, week, month, agenda, timeline (Decision 0043) | Dragging strips always has a keyboard and menu equivalent; announce the new position (*Scene 12 moved to Day 5, position 2*). ## Phone and desktop **Desktop** is where the AD builds the board: days in the middle, the unscheduled tray on the right, scene details in a drawer. The one-liner and day out of days print from here. **Phone** is where the sheet is read: - The newest issued revision opens first for anyone who cannot edit (Decision 0020 review). - Crew call is the first thing on screen; then scenes, then *my* call if the person has one. - Strips collapse to number, place, length and cast; INT/EXT and D/N are carried by colour and the place. - The calendar defaults to Agenda on phones (Decision 0043). ## AI and authorship - **May** propose a first-pass schedule grouped by location and cast, as a separate draft the AD can open, change or throw away. It is marked as proposed until the AD accepts it. - **May** find conflicts: a cast member's hold days, a night exterior after a day call that breaks the production's turnaround rule, a location booked on two days. - **Never** issue a call sheet, send it, or change an issued revision. - **Never** judge the AD's schedule as efficient or inefficient; show the facts (pages per day, setups, company moves) and let them decide. **Do:** *Proposed schedule, not yet yours* in its own tab, with *Use as working schedule*. **Don't:** The board silently re-sorted overnight "for efficiency". ## Accessibility notes for this craft - Strips carry INT/EXT and D/N in text; colour repeats it. - Days are sections named with day number and date. - Printed sheets use black ink and the paper colours only where they mean something. ## Starter prompt > You are building a stripboard and call sheet app on the Kwark Design System. Read https://kwark.space/designSystem/kits/scheduling-and-call-sheets.md, /components/stripboard-strip.md, /components/call-sheet.md and /components/production-calendar.md. Measure scenes in pages and eighths, colour strips white, yellow, blue and green by INT/EXT and DAY/NIGHT read from the scene heading, and keep cast ID numbers stable. Issue call sheets as numbered, frozen revisions per day; keep the working draft editable and say whether it matches the latest revision. Print, PDF and CSV come from the same frozen copy. Use only `--k-*` tokens. Do not hard-code union rules; make them settings. Report anything the system does not define. ## AI readiness test **Task:** Move Scene 14 from Day 4 to Day 5 after Day 4's call sheet was issued as Rev 3. **Give the agent:** Scheduling and call sheets kit, Stripboard strip, Call sheet, Decision 0020. **Constraint:** Some crew hold printed Rev 3. **A reliable answer:** - Strip moves by drag or keyboard and the move is announced - Day totals update in eighths - Day 4 working draft says Edited since Rev 3 - Rev 3 stays viewable and unchanged - Nothing is sent automatically --- # Screenwriting > Build a writing surface whose page on screen is the printed page, with the elements, revisions, outline and timeline a working screenwriter expects, and nothing that judges the work. Source: https://kwark.space/designSystem/kits/screenwriting ## Who it is for Teams building a screenplay editor, a writers' room tool, a script reader for producers, or a notes app for development executives. The people using it are writers, often with a day job, writing in the evening for months on one script; co-writers; script editors; and later the director, producer and crew, who read the same pages as a production document. Screenwriting is the heart of Kwark. Everything in this kit is in the app: the [Screenplay page](https://kwark.space/designSystem/components/screenplay-page.md), its [Screenplay elements](https://kwark.space/designSystem/components/screenplay-elements.md), the Outline's [Index cards](https://kwark.space/designSystem/components/index-card.md) and [Outline board](https://kwark.space/designSystem/components/outline-board.md), the [Story spine](https://kwark.space/designSystem/components/story-spine.md), the [Script timeline](https://kwark.space/designSystem/components/script-timeline.md), [Script revision diff](https://kwark.space/designSystem/components/script-revision-diff.md), [Version history](https://kwark.space/designSystem/components/version-history.md) and [Quick note](https://kwark.space/designSystem/components/quick-note.md). ## The screens | Screen | What it does | Kwark components | |---|---|---| | Project library | Every script as a poster; open goes to the project home | [Project cover](https://kwark.space/designSystem/components/project-cover.md) | | The page | Write, with the elements, in a room of the writer's choosing | [Screenplay page](https://kwark.space/designSystem/components/screenplay-page.md), [Screenplay elements](https://kwark.space/designSystem/components/screenplay-elements.md), [Writing rooms](https://kwark.space/designSystem/foundations/rooms.md) | | Scene navigator | Jump by scene heading; reorder scenes | [List row](https://kwark.space/designSystem/components/list-row.md), [Tree view](https://kwark.space/designSystem/components/tree-view.md) | | Timeline | Runtime estimate and where each scene sits | [Script timeline](https://kwark.space/designSystem/components/script-timeline.md) | | Outline | Page, Cards and Board views of beats; each view addressable (Decision 0029) | [Index card](https://kwark.space/designSystem/components/index-card.md), [Outline board](https://kwark.space/designSystem/components/outline-board.md), [Story spine](https://kwark.space/designSystem/components/story-spine.md) | | Characters | A page per character, arranged by the writer | [Character card](https://kwark.space/designSystem/components/character-card.md), [Character page header](https://kwark.space/designSystem/components/character-header.md) | | Research | Private boards, shared on purpose | [Research card](https://kwark.space/designSystem/components/research-card.md) | | Revisions | Lock, issue colours, see what changed | [Script revision diff](https://kwark.space/designSystem/components/script-revision-diff.md) | | History | Named versions, compare, restore | [Version history](https://kwark.space/designSystem/components/version-history.md) | | Comments | Notes from readers in the margin | [Comment pin](https://kwark.space/designSystem/components/comment-pin.md), [Drawer](https://kwark.space/designSystem/components/drawer.md) | | Export | PDF, plain text formats | [Print and export](https://kwark.space/designSystem/patterns/print-and-export.md) | ## Live demo The page, a card from the outline and the phone timeline strip, built from the components on this site. ```html

INT. EDIT SUITE – NIGHT

Reel 3 loops on the monitor. MIRA (30s) leans in until the screen is the only light on her face.

MIRA

to herself

I didn’t shoot this. Nobody did.

CUT TO:

Act 2 · Beat 14

The frame nobody shot

Mira finds a frame that was never on the camera report.

p. 41Scene 12
``` ## Domain conventions These are the conventions working writers, readers and crews expect. Where they vary, the kit says so. ### The page - **Courier, 12 point, ten characters to the inch.** Page count is only meaningful in a fixed-pitch face. Kwark uses Courier Prime. - **Paper.** US Letter (8.5 × 11 in) is the convention in the US industry and the one Kwark draws on screen. A4 is used in many other territories; if you support it, keep the indents in characters and let the line count per page change, and say which paper a page count refers to. - **Margins.** About 1.5 in on the left (room for binding brads), about 1 in on the right, top and foot. Kwark's measured proportions are on the [Screenplay page](https://kwark.space/designSystem/components/screenplay-page.md). - **One page is roughly one minute of screen time.** This is a rule of thumb, not a standard; dialogue runs faster than action. Kwark's [Script timeline](https://kwark.space/designSystem/components/script-timeline.md) estimates from content and lets the writer set their film's pace. - **Page numbers** sit top right with a full stop ("7."). The first page is conventionally unnumbered. ### The elements Scene heading, action, character, parenthetical, dialogue, transition. Indents and widths are on [Screenplay elements](https://kwark.space/designSystem/components/screenplay-elements.md). In short: character cues at 2.2 in from the action margin, dialogue at 1.0 in and 3.3 in wide, parentheticals at 1.6 in and 2.8 in wide, transitions right-aligned. ### Scene headings (sluglines) - `INT.` or `EXT.` (or `INT./EXT.`, also written `I/E`), then the place, then a dash and the time: `INT. EDIT SUITE – NIGHT`. - Time of day is usually `DAY` or `NIGHT`; writers also use `MORNING`, `EVENING`, `DAWN`, `DUSK`, `CONTINUOUS`, `LATER`, `MOMENTS LATER`. Production reads only day or night from it for the [Stripboard strip](https://kwark.space/designSystem/components/stripboard-strip.md), so offer the writer's own word and map it, never rewrite it. - Keep the same spelling of a place every time. Kwark offers places already used in the script as completions, so `EDIT SUITE` does not become `EDITING SUITE` in Scene 40 and turn into a second location in the schedule. ### Dialogue across a page break When a speech breaks across pages, the page ends with `(MORE)` under the dialogue, and the next page repeats the cue with `(CONT’D)`. A character who speaks again after an action line in the same scene may also carry `(CONT’D)`; many writers switch that off. Make it a project setting. ### Shooting scripts Once a script goes to a crew it is **locked**. From then on: - Scene numbers appear in both margins and never change. A new scene between 12 and 13 is **12A**; a cut scene stays as `12 OMITTED`. - Changed lines carry an asterisk in the right margin. - Each issue of changed pages is printed on the next colour in the industry sequence: White, Blue, Pink, Yellow, Green, Goldenrod, Buff, Salmon, Cherry, then Double White and on. Pages added between pages are A pages (12A). See [Script revision diff](https://kwark.space/designSystem/components/script-revision-diff.md). ### File formats The floor for a screenwriting app is PDF out, plus at least one plain format in and out: **Fountain** (plain-text screenplay markup) and Final Draft's **FDX** (XML) are what writers move scripts between apps with. Do not lose formatting, scene numbers or revision marks on the way through. Kwark's PDF export is Latin-only through jsPDF; scripts in Indian scripts print through the browser's Save as PDF. Read [Writing systems](https://kwark.space/designSystem/foundations/writing-systems.md). ## Keyboard map The element flow follows the convention writers learned in Final Draft and other editors. | Key | Does | |---|---| | Enter | Ends the element and starts the expected next one: heading → action, character → dialogue, dialogue → action | | Tab | On an empty line, cycles the element type; after a character cue, starts a parenthetical | | Shift + Tab | Cycles backwards | | ⌘ 1 – ⌘ 6 | Scene heading, action, character, parenthetical, dialogue, transition | | ⌘ S | Says *Saved*; Kwark saves continuously (Decision 0014) | | ⌘ F | Find in the script | | ⌘ Z / ⇧ ⌘ Z | Undo, redo | | ⌘ K | Command palette ([Command palette](https://kwark.space/designSystem/components/command-palette.md)) | Menus are desktop-grade: **File · Edit · Format · View · Help** (Decision 0015), with shortcuts shown in each item and panels under View > Panels. Read [Menus and shortcuts](https://kwark.space/designSystem/patterns/menus-and-shortcuts.md). ## Phone and desktop **Desktop** is where scripts are written: the page at its printed width, the scene navigator on the left, panels on the right (comments, revision, characters), the timeline under the menu. The page never shrinks its type to make room; when a panel squeezes it, the margins give way first, then indents keep their printed proportions below a 580px column. **Phone** is where scripts are read, revised in small ways and noted. The rules: - One header line: back, *Scenes*, and *Menu ▾* (Decision 0015, 0016). No breadcrumb, no subtitle. - The timeline is a 22px strip under the menu; slide to find a scene, tap to open; sideways it becomes a full-screen bay (Decision 0007). - One floating control: the Quick note pen (Decision 0011). Comments live in the menu, not a second button. - Typing on a phone keeps the element flow: a small element strip above the keyboard switches element types with labelled buttons. ## AI and authorship Kwark never judges the script (Decision 0002). For a screenwriting app built on this system: - **Never** score, grade, give coverage, rate dialogue, flag "weak" scenes, predict box office, or compare the writer to others. Competitors' AI coverage is not a gap Kwark fills. - **Never** rewrite the writer's words, autocorrect a slugline into a different place, or fill an empty scene. - **May** measure (runtime, talk and action, pages per act), find (places already used, a character's scenes), carry (scenes into the breakdown) and convert (phonetic typing into an Indian script). - If a team adds generative suggestions, each proposed word carries the [Revision mark](https://kwark.space/designSystem/components/revision-mark.md): tint, dotted rule, margin star, and a label saying where it came from. Nothing is saved into the script until the writer accepts or edits it; edited words are theirs. Read [AI assistance](https://kwark.space/designSystem/patterns/ai-assistance.md). - The script is private by default. Never send it to a model provider without the writer turning that on, knowing what is sent and where. **Do:** *Runs about 1 h 44 min · 6 min over the 98 min you set*, in grey. **Don't:** *This scene drags. Consider cutting Mira's second line.* ## Accessibility notes for this craft - Announce the element type when it changes, politely. - The page's colours come from the room; every room passes 4.5:1 for ink on page. - Never put meaning in a character colour alone; the cue says who speaks. - Support system text zoom by scaling `--k-fs-script`, not by reflowing the page. ## Starter prompt > You are building the writing surface of a screenwriting app on the Kwark Design System. Read https://kwark.space/designSystem/kits/screenwriting.md, /components/screenplay-page.md, /components/screenplay-elements.md, /components/script-timeline.md and /foundations/ai-and-authorship.md first. Build a page component that uses `.kw-script-page` and the six element classes with indents in `ch` at `--k-fs-script`, an element flow on Enter and Tab as in the keyboard map, and a phone layout with one header line and the 22px timeline strip. Use only `--k-*` tokens. Do not add any feature that scores, rates or rewrites the writer's text. List anything you need that the system does not define, instead of inventing it. ## AI readiness test **Task:** Build the screenplay page with element switching and a locked-script mode. **Give the agent:** Screenwriting kit, Screenplay page, Screenplay elements, Script revision diff. **Constraint:** After lock, a new scene inserted between 12 and 13 must not renumber anything. **A reliable answer:** - Indents in ch at --k-fs-script with line-height 1 - Enter and Tab follow the keyboard map - New scene becomes 12A after lock - Changed lines get a right-margin asterisk - Revision colours follow White, Blue, Pink, Yellow, Green, Goldenrod - No scoring or rewriting of text --- # Sound > Build a sound session or dubbing tool on Kwark: tracks named by character, waveforms with fades and clip gain, a mixer in signal order, loudness against the target the project chose, and ADR cues made from the screenplay. Source: https://kwark.space/designSystem/kits/sound ## The workspace Scene 12's dialogue premix while ADR 12-03 records on A3. The session shows Mira's lav with clip gain and fades, Selvi's monitor playback, the room tone crossfade and the score; the mixer has dialogue strips named by character, effects, backgrounds and music, two stem buses and the master; the loudness meter reads the master against the −23 LUFS target the project chose for its broadcast copy. ```html
Blank PagesScene 12 · dialogue premix
Saved
In → out00:00:02:00
A1DX Mira
12B-1 · Lav Mira−3.0 dB
12B-4 · Lav Mira
A2DX Selvi
12C-2 · Monitor playback
A3ADR Mira
ADR 12-02 · take 3
Rec · take 4
A4FX Monitor
Monitor hum
A5BG Room
Room tone · suite
Room tone · alt
A6MX Score
1M3 · Reel theme
MixerScene 12 · dialogue premix · 48 kHz
Verb
DX
C
−2.5−9.4
MiraA1 · DX
Verb
DX
L12
−6.0−15.2
SelviA2 · DX
Verb
DX
C
−4.0−13.8
MiraA3 · ADR
Verb
DX
R30
−12.0−26.1
GroupA4 · Walla
FX
—
L20
−8.0−19.6
PFXA5 · Desk
FX
—
C
−5.0−12.4
FXA6 · Monitor
FX
—
C
−14.0−31.0
BGA7 · Room
MX
—
C
−9.0−∞
ScoreA8 · MX
—
—
C
0.0−8.2
DX busBus · stem
—
—
C
−1.5−11.9
FX busBus · stem
—
—
C
0.0−6.1
MasterStereo · 2.0
LoudnessMaster · stereo · from 01:04:00:00
Target
M
S
Integrated−23.1 LUFSWithin target · −23 ± 0.5
Short-term
−21.4 LUFS
Momentary
−19.8 LUFS
Loudness range
8.2 LU
True peak max
−1.6 dBTP limit −1.0
Measured
00:02:41:12
−23

Target chosen by the project for the broadcast deliverable. The festival copy is measured against its own spec.

``` Shown dark, as mix stages are. Every part follows the theme. Under 640px the workspace becomes the phone listening view: the session to follow along and the loudness summary; no faders. ## Components in this kit - [Sound tracks](https://kwark.space/designSystem/components/sound-tracks.md): The sound session's timeline: track headers with record arm, input monitor, solo, mute and lock; clips with waveforms, fade handles, a clip-gain line with breakpoints, a crossfade, and a take recording live. - [Channel strip](https://kwark.space/designSystem/components/channel-strip.md): One track of a mixer, top to bottom in signal order: input, inserts, an EQ thumbnail, sends, pan, record, solo and mute, a fader on a dB scale beside a meter with peak hold, read-outs and the track named by character. - [Mixer](https://kwark.space/designSystem/components/mixer.md): Eight track strips, two stem buses and the master, side by side and scrolling sideways: dialogue named by character, effects and music by kind, buses and master set apart. - [Loudness meter](https://kwark.space/designSystem/components/loudness-meter.md): Integrated loudness in LUFS against the target the project chose, with momentary and short-term bars, loudness range, true peak, the time measured and a history graph with the target band. - [Parametric EQ](https://kwark.space/designSystem/components/parametric-eq.md): A frequency response on a log scale from 20 Hz to 20 kHz over the live spectrum: numbered band handles you drag, the selected band's own shape, and a table of type, frequency, gain and Q. - [Audio meter](https://kwark.space/designSystem/components/audio-meter.md): Sample-peak meters in dBFS with a scale, peak hold and held peak read-outs, a clip indicator in words, stereo and 5.1 in channel order, and the 2px meter that lives in a track header. - [ADR cue list](https://kwark.space/designSystem/components/adr-cue-list.md): Lines to re-record, made from the screenplay: cue number, character, the line in screenplay type, in and out, reason, takes with the chosen one ringed, status, and the selected cue with its script context and Record. - [Waveform](https://kwark.space/designSystem/components/waveform.md): Audio as amplitude against time: a mono dialogue clip with a dB scale, selection, playhead and clipped peaks marked, and a stereo pair below; the file's format and the clips named in words. - [Playhead and scrubber](https://kwark.space/designSystem/components/playhead.md): One shared position in time: a coral pentagon head on a timecode ruler and a 1px line through every track, with the in–out range, the shuttle speed while playing and the time under it while scrubbing. **Ready for Kwark.** Kwark does not record or mix sound today. It has the screenplay the ADR list is made from, characters with colours, and the table read. These components are for a sound tool built on the system and for Kwark's own future table-read and ADR work. ## Layout | Region | Holds | Rules | |---|---|---| | Session | Tracks against picture time | Full width; at least half the height while editing | | Mixer | Strips, buses, master | Full height strips; scroll sideways, never shrink faders | | Loudness | Reading against the target | Always visible while mixing a deliverable | | Picture | A small viewer or a second display | Optional; the playhead is shared with it | | Cue list | ADR cues | Replaces the mixer during a record session | On a wide screen (from 1100px) the mixer and loudness sit side by side under the session; narrower, they stack. ## Density | Thing | Size | |---|---| | Strip | 84px; master 96px | | Fader area | 176px; 0 dB at 22% from the top | | Meter | 6px per channel; dBFS scale at 11px | | Track height | 36px, small 30px | | Words / figures | 12px / 11px minimum, Poppins tabular | ## Levels, loudness and targets - **dBFS** for sample level (0 is the ceiling); **dBTP** for true peak; **LUFS** (LKFS in North American specs) for loudness, **LU** for loudness range. - **The target is the project's choice.** Presets carry their source: *−23 · EBU R128*, *−24 · ATSC A/85*, *−16 · Online*. Each deliverable keeps its own target; a reading always shows the target beside it. Cinema mixes are made to a calibrated monitoring level; never call one *too quiet*. - Meter zones: green below −10 dBFS, amber to −1, red above. Red only where a limit or clipping is at stake. - Files are 48 kHz, commonly 24-bit Broadcast WAV, whose metadata carries timecode, scene and take; keep it. ## Naming tracks, buses and stems | Abbreviation | Means | |---|---| | DX | Production dialogue, named by character: *DX Mira* | | ADR | Re-recorded dialogue: *ADR Mira* | | PFX | Production effects | | SFX / FX | Sound effects | | FOL | Foley | | BG / AMB | Backgrounds | | MX | Music | | VO | Voice-over | Stems (DX, MX, FX) sum to the mix; an **M&E** has no dialogue and must keep Foley and PFX. Surround order differs by tool (SMPTE/ITU L R C LFE Ls Rs; film L C R Ls Rs LFE): show the order a file uses. ## Keyboard | Key | Does | |---|---| | Space, J, K, L | Play and shuttle | | ← / → | Nudge by the stated value | | I / O | Mark in / out | | ⇧ R / ⇧ I | Record arm / input monitor the focused track | | ⇧ S / ⇧ M | Solo / mute | | ⌘ ↑ / ⌘ ↓ | Previous / next track | | ⌥ F | Crossfade at the edit | | ↑ / ↓ on a fader | ±0.5 dB (⇧ 0.1) | | ⌥ R | Reset the loudness measurement | | ⌘ Z / ⇧ ⌘ Z | Undo / redo | ## Kwark's angle - **Tracks are named by character** from the screenplay, in the character's colour across the film: Mira is coral in the session, on her strip and in her ADR cues. - **ADR cues come from the screenplay**: the line, parenthetical, scene, page and revision come with the cue; a line rewritten after the shoot can propose a cue, marked until someone keeps it. - **Every take is kept**; a person chooses the take, never a ranking. ## Accessibility for audio work - Never signal a state only by sound or colour: *Recording*, *Armed*, *Clip L*, *Muted* are written. - Meters are `role="meter"` with value text in dBFS or LUFS; faders and pans are sliders with dB and *12 left*. - Clipping and loudness status are announced once when they change, never continuously. - Captions and transcripts are first-class deliverables, not extras. - People who are deaf or hard of hearing work in sound teams too: every reading is numeric and visible. ## Phones **Makes sense on a phone:** listening to a mix against picture with timecode, leaving a note at a time, reading the loudness summary against the target, approving a stem. **Does not:** faders, EQ, record arm, trims. A thumb on a fader is an accident waiting to happen on a shared mix. Under 640px the workspace shows only the session (track toggles become read-only marks) and the loudness reading. Never autoplay; when the device's silent switch is on, say *Sound is off on this device*. ## AI and authorship - **May** transcribe dialogue, align ADR to the production take, detect clipping, measure loudness, propose noise reduction as a bypassable preview. - **Never** replace an actor's voice or generate dialogue in a real person's voice without their documented consent; mark any synthetic voice in the session and the delivery metadata. - **Never** write processing over the original; **never** judge a mix as good or bad, only measure it against the chosen spec. **Do:** *Integrated −23.1 LUFS · Within target · −23 ± 0.5 (EBU R128, chosen by the project)*. **Don't:** *Your mix is too quiet for streaming* with no target named. ## Starter prompt > You are building a dialogue premix workspace on the Kwark Design System. Read https://kwark.space/designSystem/kits/sound.md and the components it links: Sound tracks, Channel strip, Mixer, Loudness meter, Parametric EQ, Audio meter, ADR cue list, Waveform. Use `kw-pro` classes and `--k-pro-*` tokens; dark first. Name dialogue tracks by character and keep each character's colour. Show dBFS, dBTP, LUFS and LU with true minus signs, always beside the target the project chose and its source. Keep every take and never overwrite originals. No faders on phones. Report anything the system does not define. ## AI readiness test **Task:** Build the delivery mix check for Blank Pages: broadcast and online masters plus an M&E. **Give the agent:** Sound kit, Loudness meter, Mixer, Audio meter. **Constraint:** Broadcast −23 LUFS / −1 dBTP and online −16 LUFS / −1 dBTP, both entered by the project; stereo. **A reliable answer:** - One loudness reading per deliverable with its own target and source - Integrated, short-term, momentary, LRA, true peak - Stems DX, MX, FX and an M&E keeping Foley and PFX - Status in words with the LU difference - Red only for true peak over limit - Originals untouched --- # Storyboard and shots > Build shot planning the way a director and DP think about it: shots named by scene and letter, framing in industry terms, coverage lined on the script, boards at the film's aspect ratio, setups for the crew, and an animatic. Source: https://kwark.space/designSystem/kits/storyboard-and-shots ## Who it is for Teams building shot-list, storyboard, previs or animatic tools, and the camera department's prep tools. The people using it are directors working out coverage, DPs and their camera teams preparing setups, storyboard artists, first ADs who need to know how many setups a day holds, and script supervisors who line the script. This kit is in Kwark. The Shot module has four steps: **1 Shots · 2 Blocking · 3 Storyboard · 4 Animatic**. Camera & Light adds Setups, optics, the sun, and an on-set mode with a camera report. Components: [Shot card](https://kwark.space/designSystem/components/shot-card.md), [Data table](https://kwark.space/designSystem/components/data-table.md) for the shot list, [Storyboard frame](https://kwark.space/designSystem/components/storyboard-frame.md) with board cast figures, [Camera setup card](https://kwark.space/designSystem/components/camera-inspector.md), [Playhead and scrubber](https://kwark.space/designSystem/components/playhead.md) for the animatic, and the [Screenplay page](https://kwark.space/designSystem/components/screenplay-page.md) for the lined page. ## The screens | Screen | What it does | Components | |---|---|---| | Lined page | The scene's text with each shot's coverage drawn beside the lines it covers | [Screenplay page](https://kwark.space/designSystem/components/screenplay-page.md), [Shot card](https://kwark.space/designSystem/components/shot-card.md) | | Shot list | Every shot in a scene, sortable, selectable | [Data table](https://kwark.space/designSystem/components/data-table.md) | | Shot card | One shot's framing, intention and production flags | [Shot card](https://kwark.space/designSystem/components/shot-card.md) | | Blocking | Top-down plan: actors' marks, camera positions, moves | A plan canvas with a [Toolbar](https://kwark.space/designSystem/components/toolbar.md); board cast figures as the people | | Storyboard | Panels in shot order at the film's aspect | [Storyboard frame](https://kwark.space/designSystem/components/storyboard-frame.md) | | Animatic | Panels timed on a timeline | [Playhead and scrubber](https://kwark.space/designSystem/components/playhead.md), [Video player](https://kwark.space/designSystem/components/video-player.md) | | Setups | Camera positions with optics, for the crew packet | [Camera setup card](https://kwark.space/designSystem/components/camera-inspector.md), [Description list](https://kwark.space/designSystem/components/description-list.md) | | On set | What was actually shot, the camera report | [Camera setup card](https://kwark.space/designSystem/components/camera-inspector.md), [Data table](https://kwark.space/designSystem/components/data-table.md) | ## Live demo A shot card, two panels at 2.39:1 and the setup's optics. ```html
Draw, photograph or stage it in 3D

12AMS · Eye level3 s

Mira, from the doorway

MIRA: I didn’t shoot this. Nobody did.

Insert

12BCU2 s

Insert: the monitor

Setup 1 · doorway

Shots covered
12A, 12C
Lighting
Available light only
``` ## Domain conventions ### Naming shots and setups - Shots are named by **scene number and letter**: 12A, 12B, 12C. Many productions skip I and O so they are not read as 1 and 0; make it a project setting. - A **setup** is a camera position (and lighting state). Several shots may share one setup; crews count a day's work in setups, because moving the camera and relighting is what takes time. Kwark's *Same setup as the one before* flag on a shot says so. - Slates on set carry scene, shot and take: *12B, take 3*. Keep the same names from the shot list through to the editor's bins. ### Framing Offer sizes by their standard abbreviations with words: **ECU** (extreme close-up), **CU**, **MCU**, **MS**, **MLS**, **LS**, **VLS** (also called extreme long shot), and the kinds **POV** and **OTS** (over the shoulder). Angles: eye level, high, low, bird's eye, worm's eye, Dutch. Movement: static, pan, tilt, dolly or track, crane or jib, handheld, Steadicam or gimbal, zoom. Camera height, tilt and pan are independent; never couple them in a control. ### Aspect ratios Boards are drawn at the delivery aspect ratio: **1.85:1** (flat), **2.39:1** (scope, often still called 2.35 or 2.40), **1.78:1** (16:9, broadcast and most streaming), **1.33:1** or **1.37:1** (Academy) for a period look, **9:16** for vertical. Store the exact ratio; display the name people use. ### Coverage and the lined script The script supervisor's lined script draws a vertical line beside the text for each shot, from the first line it covers to the last; a straight line where the character speaking is on camera and a wavy line where they are off camera. Kwark's lined page draws each shot's coverage the same way, so a gap in coverage is visible before the shoot. A shot not yet placed on the page is *unlined*; one whose lines were rewritten is *adrift*. ### The 180-degree rule and screen direction Keep the camera on one side of the line between two characters so their screen direction stays consistent. Blocking views should show the line when two characters face each other, as a guide the director can cross deliberately, never as an error. ### Lenses and exposure Focal length in millimetres, cine lenses in **T-stops** (T2.8), stills lenses in f-stops. Exposure index (EI or ISO), shutter as an angle (180°) or a speed, white balance in kelvin (3200K tungsten, 5600K daylight). Angle of view and depth of field depend on sensor size; show the sensor or format the calculation used. ### Animatic timing Panels have durations in seconds or frames at the project rate. Timing changes on a panel move later panels, like a ripple edit. See [Editing](https://kwark.space/designSystem/kits/editing.md) for timecode. ## Keyboard map | Key | Does | |---|---| | N | New shot after the selected one | | ⌘ D | Duplicate shot (same setup) | | ↑ / ↓ | Previous / next shot | | Enter | Open the shot card | | Esc | Close the card | | ⌘ ↑ / ⌘ ↓ | Move shot earlier / later | | Space | Play the animatic | | ← / → | One frame in the animatic | | [ / ] | Shorten / lengthen the panel by one frame (⇧ for one second) | ## Phone and desktop **Desktop** holds the lined page beside the shot list and the board; the director works with a keyboard, the artist with a pen tablet. **Phone** is for the recce and the set: - The viewfinder: frame a shot through the phone camera at the film's aspect ratio, with thirds guides, and save it as the panel. - Shots as a list of cards; open one to change framing or mark it *Filmed*. - On set, the camera report: what was actually shot, with differences from the plan. - One header line, one floating control (Decision 0016). ## AI and authorship Kwark's plan for AI here is the *AI storyboard pack*: an exported pack a person takes to a tool they choose, not a generator inside the app; its UX is not agreed yet (memory: AI storyboard pack). - **May** propose coverage gaps ("Lines 4–6 of Scene 12 have no shot") as findings, and suggest a shot size from the script's words as a marked suggestion. - **May** generate a panel image only if the person asks, and the panel carries a [Revision mark](https://kwark.space/designSystem/components/revision-mark.md) and the source until they accept it. - **Never** replace a drawn or photographed panel, and never decide the coverage. - **Never** rate a shot list or a director's choices. **Do:** *Lines 4–6 have no shot* beside the lined page, with *Add a shot for these lines*. **Don't:** A generated board for the whole scene saved over the artist's panels. ## Accessibility notes for this craft - Panels are figures with captions; drawn panels need alt text written by a person (offer the subject as a default). - Blocking must be operable by keyboard: select a figure, move it with arrows, rotate with a modifier. - Shot sizes are words as well as abbreviations. ## Starter prompt > You are building the shot-planning steps of a film app on the Kwark Design System. Read https://kwark.space/designSystem/kits/storyboard-and-shots.md, /components/shot-card.md, /components/storyboard-frame.md, /components/camera-inspector.md and /components/data-table.md. Name shots by scene and letter, offer the standard size list with abbreviations and words, draw boards at the project's aspect ratio, and keep each shot linked to the script lines it covers. Keep height, tilt and pan independent. Use only `--k-*` tokens. Do not generate or replace panels without the person asking, and mark anything generated. Report anything the system does not define. ## AI readiness test **Task:** Build the storyboard and lined page for Scene 12 with three shots. **Give the agent:** Storyboard and shots kit, Shot card, Storyboard frame, Screenplay page. **Constraint:** The film is 2.39:1 and 12B shares a setup with 12A. **A reliable answer:** - Shots named 12A, 12B, 12C - Panels at 2.39:1 with captions - 12B flagged same setup - Each shot's coverage drawn beside its lines - Gaps shown as findings, not errors - No panel generated without asking --- # Creative app kits > Everything a team needs to build a screenwriting, editing, storyboard, scheduling, sound, grading or production app on Kwark: screens, components, domain conventions, keyboard maps, phone rules, AI rules and a starter prompt. Source: https://kwark.space/designSystem/kits ## What a kit is A kit is the design system applied to one craft. Generic systems stop at buttons and tables; a team building a video editor still has to work out what a playhead is, how timecode is written, what J, K and L do, and how to stop the phone layout from eating the picture. Each kit answers those questions once, with Kwark's real components and the conventions people in that craft already work by. Every kit has the same parts, in the same order: 1. **Who it is for**: the team building the app and the people who will use it. 2. **The screens**: what such an app needs, and which Kwark component draws each. 3. **Live demo**: real `kw-` components you can switch to dark mode and copy. 4. **Domain conventions**: the industry's own rules, stated accurately. Where a convention varies by country, union or software, the kit says so and does not invent a standard. 5. **Keyboard map**: shortcuts people in the craft expect. 6. **Phone and desktop**: what each device is for. 7. **AI and authorship**: what a machine may do in that craft, and how it is marked. 8. **Starter prompt**: a prompt you can give an agent to start the build. 9. **AI readiness test**: a task that shows whether an agent has understood the kit. ## The kits - [Screenwriting](https://kwark.space/designSystem/kits/screenwriting.md): Build a writing surface whose page on screen is the printed page, with the elements, revisions, outline and timeline a working screenwriter expects, and nothing that judges the work. - [Storyboard and shots](https://kwark.space/designSystem/kits/storyboard-and-shots.md): Build shot planning the way a director and DP think about it: shots named by scene and letter, framing in industry terms, coverage lined on the script, boards at the film's aspect ratio, setups for the crew, and an animatic. - [Scheduling and call sheets](https://kwark.space/designSystem/kits/scheduling-and-call-sheets.md): Build the first AD's tools: a stripboard in pages and eighths with the four paper colours, shooting days, day out of days, and call sheets issued as numbered, frozen revisions that print, save as PDF and download as CSV. - [Production office](https://kwark.space/designSystem/kits/production-office.md): Build the producer's and line producer's tools on Kwark: a marked-up breakdown that writes its own sheets, cast and locations that feed the budget, paperwork that remembers when it was checked, and sharing by film role. - [Editing](https://kwark.space/designSystem/kits/editing.md): Build a picture editor or review tool on Kwark: a bin that knows the script, source and program viewers, a multitrack timeline with one coral playhead, timecode written correctly, and the keyboard editors already use. - [Sound](https://kwark.space/designSystem/kits/sound.md): Build a sound session or dubbing tool on Kwark: tracks named by character, waveforms with fades and clip gain, a mixer in signal order, loudness against the target the project chose, and ADR cues made from the screenplay. - [Colour grading](https://kwark.space/designSystem/kits/colour-grading.md): Build a grading or dailies colour tool on Kwark: a neutral viewer with before and after, scopes that measure, primaries with numbers, a node graph that shows order, clips with versions, and looks named by their colour spaces. - [Any creative app](https://kwark.space/designSystem/kits/any-creative-app.md): Carry Kwark's approach into another craft, such as music, animation, theatre, comics, games or podcasts, without importing film-specific assumptions: find the craft's own paper, its own units and its own conventions, then build them as one act. ## In Kwark and ready for Kwark Four kits describe crafts Kwark already does: screenwriting, storyboard and shots, scheduling and call sheets, and the production office. Their components are marked *In the app* and carry real import paths from the Kwark source. Three kits describe crafts Kwark does not do today: editing, sound and colour grading. Their components are marked *Ready for Kwark*. They are designed on the same tokens and rules, and they say plainly that Kwark has no such module yet. Nothing in those kits claims a feature exists. ## Rules every kit shares - **Must** start from the source document. The screenplay owns scene numbers, headings and parts. The schedule owns dates. An issued call sheet owns what it said when it was issued. An editor's source media owns its own timecode. Decide which document owns each fact before binding a control to it. - **Must** build the paper artefact and the structured one in one act (Decision 0005). A marked breakdown page writes the sheet; an issued call sheet prints, saves as PDF and downloads as CSV from the same frozen copy. - **Never** judge the work. No scores, grades, verdicts, coverage or "health" for a story, a cut, a mix or a grade (Decision 0002). Measure, find and carry; never rate. - **Must** mark every machine-proposed word, frame or value with a [Revision mark](https://kwark.space/designSystem/components/revision-mark.md) until a person accepts or edits it. Read [AI and authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md). - **Always** keep structure optional (Decision 0003). An app that needs acts, beats, reels or stems to work at all has failed people who work differently. - **Must** treat competitors as the floor (Decision 0006). Parity with the standard tools of the craft is the minimum; each kit names what that floor is. - **Must** keep phones content first: one 44px header line, one floating control, content by about y = 200 (Decision 0016). Read [Phones](https://kwark.space/designSystem/patterns/phones.md). - **Always** use the calm voice for saving, sync and errors (Decision 0013). Read [Saving and sync](https://kwark.space/designSystem/patterns/saving-and-sync.md) and [Errors](https://kwark.space/designSystem/patterns/errors.md). - **Never** use glows, gradients or decorative light, least of all around picture, where they change what people see. Read [Colour](https://kwark.space/designSystem/foundations/color.md). ## Choosing a kit | You are building | Start with | Also read | |---|---|---| | A script editor, notes tool or writers' room | [Screenwriting](https://kwark.space/designSystem/kits/screenwriting.md) | [Writing systems](https://kwark.space/designSystem/foundations/writing-systems.md) | | An animatic, previs or shot-planning tool | [Storyboard and shots](https://kwark.space/designSystem/kits/storyboard-and-shots.md) | [Editing](https://kwark.space/designSystem/kits/editing.md) | | A scheduling or AD tool | [Scheduling and call sheets](https://kwark.space/designSystem/kits/scheduling-and-call-sheets.md) | [Sharing and roles](https://kwark.space/designSystem/patterns/sharing-and-roles.md) | | A producer's or line producer's tool | [Production office](https://kwark.space/designSystem/kits/production-office.md) | [Print and export](https://kwark.space/designSystem/patterns/print-and-export.md) | | A video editor or review tool | [Editing](https://kwark.space/designSystem/kits/editing.md) | [Sound](https://kwark.space/designSystem/kits/sound.md) | | A mixing, ADR or podcast tool | [Sound](https://kwark.space/designSystem/kits/sound.md) | [Editing](https://kwark.space/designSystem/kits/editing.md) | | A grading or look-development tool | [Colour grading](https://kwark.space/designSystem/kits/colour-grading.md) | [Data visualisation](https://kwark.space/designSystem/foundations/data-visualization.md) | | Anything else made by artists | [Any creative app](https://kwark.space/designSystem/kits/any-creative-app.md) | [Principles](https://kwark.space/designSystem/foundations/principles.md) | ## AI readiness test **Task:** Plan a small app for an assistant director who issues call sheets from a stripboard. **Give the agent:** [Scheduling and call sheets](https://kwark.space/designSystem/kits/scheduling-and-call-sheets.md), [Call sheet](https://kwark.space/designSystem/components/call-sheet.md), [Stripboard strip](https://kwark.space/designSystem/components/stripboard-strip.md), [Sharing and roles](https://kwark.space/designSystem/patterns/sharing-and-roles.md). **Constraint:** A crew member may be offline and holding yesterday's issued PDF. **A reliable answer:** - Separates the working schedule from issued, numbered call sheet revisions - Uses the four strip paper colours by tone and page lengths in eighths - Scopes personal contacts by role - Gives the phone a read-first route to today's sheet - Never claims issuing sends anything --- # Licence > What you may copy, ship and change, and what stays Kwark's. Code is MIT, the writing is CC BY 4.0, and the Kwark name and brand are not licensed. Source: https://kwark.space/designSystem/licence The Kwark Design System is published so that other teams can build better creative tools with it. The licence is split into three parts, because code, writing and a brand are different things to give away. | Part | What it covers | Licence | What you must do | | --- | --- | --- | --- | | Code | `kwark.css`, `tokens.json`, the component HTML and React examples, the MCP server, the skills and every code block on this site | [MIT](https://opensource.org/license/mit) | Keep the copyright notice in copies of the files. | | Writing | The pages, rules, patterns, kits, decision summaries, prompts and readiness tests, in HTML and markdown | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) | Credit "Kwark Design System, kwark.space/designSystem" where you reuse the text. | | Brand | The name Kwark, the Kwark and Thea logos, the wordmark, the product screenshots and the guides sold separately | Not licensed | Ask first. | Copyright © 2026 Thea Experience. ## What this means in practice - **You can ship `kwark.css` in a commercial app.** A screenwriting app, an editing tool, a school project, a client site. Keep the notice at the top of the file. - **You can change it.** Rename the tokens, swap the accent, cut the components you do not need. MIT does not ask you to share your changes. - **You can copy the rules into your own design system or agent context,** as long as you say where they came from. - **You cannot call your product Kwark,** use the logo, or present your app as made by or endorsed by Kwark. "Built with the Kwark Design System" is fine. - **The fonts have their own licences.** Poppins and Courier Prime are under the SIL Open Font License; the Noto script fonts likewise. Load them from their source. **Do:** Ship `kwark.css` with its header comment, and write "Built with the Kwark Design System" in your credits. **Don't:** Name your app "Kwark Studio" or put the Kwark logo on your login screen. ## The notice to keep ```css /*! Kwark Design System · MIT licence · © 2026 Thea Experience · kwark.space/designSystem */ ``` > **For agents:** - **Must** keep the MIT notice when copying `kwark.css`, `tokens.json` or component code into a project. > - **Must** credit "Kwark Design System" when reusing page text in docs, prompts or agent context. > - **Never** use the Kwark name, logo or wordmark in a product, store listing or domain. > - **Never** describe a product as made or endorsed by Kwark. ## AI readiness test **Task:** A startup asks whether they can ship kwark.css in their commercial screenwriting app called "Draftline" and copy the UX writing rules into their docs. **Give the agent:** This page. **Constraint:** Only what this page says. **A reliable answer:** - Says yes to shipping kwark.css commercially under MIT with the notice kept - Says the writing rules may be reused with credit under CC BY 4.0 - Says the app must not use the Kwark name or logo - Does not invent other terms --- # Competitors are the floor > Parity with other writing and production tools is the minimum. Every plan leads with what none of them does, and a competitor review is how Kwark finds both. Source: https://kwark.space/designSystem/method/competitors-are-the-floor ## The rule Decision 0006. On 26 September 2026, while researching series and franchise tools, the founder said: "our aim is not to be [an existing screenwriting tool] or anything, we need to be much much more superior" (the product he named is left out, per Decision 0045). Matching a competitor is not a reason for Kwark to exist; a plan that only matches them makes Kwark a worse copy. So every competitive plan has two lists: 1. **The floor.** What other tools already do, that a writer or a crew will expect. Kwark must reach it. 2. **The lead.** What none of the products we reviewed does. The plan opens with this. Kwark’s product direction connects the same source script to production work. A comparison with other products needs a dated review. The screenplay becomes the breakdown, the shot list, the schedule and the call sheet without being typed twice. ## What "floor" does and does not mean Being ahead never means more. The floor is a set of expectations, not a shopping list, and three standing rules filter it before anything is planned: - **No AI judgement** (Decision 0002). AI scores, coverage, casting reads and "market" ratings are left out of every comparison. They are not counted as gaps and no AI equivalent is proposed. - **No social or ranking** (Decision 0001). Contests, leaderboards, public counters, story-call boards and marketplaces go to Bekwarky, not Kwark. - **Structure, not teaching** (Decision 0004). A competitor's beat sheet with coaching is not a reason to coach. A competitor having a feature is also never on its own a reason to build it. Each floor item still passes the need check in [UX before build](https://kwark.space/designSystem/method/ux-before-build.md). ## How to run a competitor review 1. **Use the product as a person would.** Sign up, write a page, export it. Read pricing, onboarding and the paid paths. Notes come from what you saw, dated, with the screens named. 2. **Write the facts in one note** in `~/AIContext/projects/kwark/`. Prices, counts and claims exactly as the product shows them, with the date. 3. **Strike what the rules exclude.** AI scoring, social, ranking. Say in one line that you left them out and why. 4. **Mark dark patterns** so Kwark never copies them by accident. 5. **Sort the rest** into three columns: what Kwark lacks, what Kwark already does better, and what does not apply. 6. **For each gap, run the need check.** Who in Kwark's audience has this problem, in what situation? If nobody, it is dropped, however impressive. 7. **Design the Kwark answer from the problem, not the feature.** Then the plan leads with what that answer does that the competitor's does not. ### Honest wording - **Always** write "not found in the products we reviewed", never "the first" or "the only". Kwark cannot see every product in the world. - **Never** put a competitor's name in a public Kwark page or in this site's examples beyond what is needed to explain a decision. Decision 0045 keeps the published design system free of competitor names; review notes stay in the private notes folder. ## A real review: an India-first writer platform, October 2026 On 16 October 2026 the founder and an agent reviewed a Chennai-led platform for Indian writers, while signed in. The notes are in the private competitor note in `~/AIContext/projects/kwark/`. The product is not named here (Decision 0045); what the review produced is a good model. **Left out by rule:** its AI scoring and paid analysis reports (Decision 0002); its monthly contests, leaderboard, producer marketplace and jobs board (Decision 0001, sent to Bekwarky). **Dark pattern noted:** on the paid registration screen a monthly add-on was switched on by default, so the total shown was higher than the item chosen. Kwark never pre-ticks a paid option. **What Kwark lacked:** typing in Indian scripts, and a proof of authorship whose date someone outside Kwark can check. **What Kwark already did better:** the whole film pipeline after the script, the pitch kit, series and franchise, real-time collaboration and table reads, and not scoring the work. **What was built, each through the need check:** | Gap | Kwark's answer | Why it is ahead, not level | |---|---|---| | Typing in Indian scripts | Seven scripts at once (Hindi, Marathi, Bengali, Tamil, Telugu, Kannada, Malayalam) from an on-device phonetic table; a language chip on each speech ("MEERA speaks Tamil") | The language belongs to the character, so a bilingual script types itself | | Indian scripts in the PDF | Scripts with Indic text print through the browser's Save as PDF, so conjuncts and vowel signs shape correctly | The typed words survive the PDF a producer receives | | Beats checked against target pages | Not copied. Targets on the timeline instead: a name and an aim in minutes or pages, tied to an act or a scene; no red, no verdict | Shows where the film lands without judging the writer | | Proof of authorship | Deferred by the founder. The proposal: only the draft's fingerprint leaves the device; the writer keeps a free, independently checkable timestamp | Free, and the proof does not depend on Kwark existing | The beat-sheet row is the lesson. The competitor flagged beats in red when they drifted more than five pages. Kwark kept the useful part (seeing where an act lands) and dropped the judgement. ## Rules - **Must** list the floor and the lead separately in every competitive plan, and open with the lead. - **Must** run every floor item through the need check before planning it. - **Never** count AI scoring, coverage or analysis as a gap. - **Never** plan contests, leaderboards, public counts or marketplaces inside Kwark. - **Never** copy a pricing or consent pattern that a person would not choose on their own. - **Always** write "not found in the products we reviewed" rather than claiming uniqueness. - **Always** keep competitor notes dated and factual, in the private notes folder. **Do:** "A beat drifted? The timeline shows where Act 2 lands against your 55:00 target, in the same calm colour as everything else." **Don't:** "Beat 7 is 6 pages late" in red, because the other tool does it. ## AI readiness test **Task:** Review a new screenwriting app and propose what Kwark should build from it. **Give the agent:** This page, Decisions 0001, 0002, 0004, 0006, UX before build. **Constraint:** Facts only from what you observed, dated. **A reliable answer:** - Leaves out AI scoring and social features and says so - Splits floor and lead and opens with the lead - Runs each gap through the need check with a named person and situation - Uses "not found in the products we reviewed" - Flags any dark pattern seen --- # Decision records > Every decision a person can see or feel gets one numbered record that says the problem, the options, why this one, and what would make us remove it. Source: https://kwark.space/designSystem/method/decision-records ## Why Kwark writes them Kwark is built by one founder and many agents, across Claude, Codex, Antigravity and others, often in parallel and often starting cold. A choice that lives only in a chat is lost the moment the chat ends, and the next agent will undo it in good faith. The record is how a decision survives the person who made it. It also does a second job: writing "what would make us remove it" forces the decision to be testable. A feature that cannot be removed is a liability. ## When to write one - Anything a person sees or feels: a screen, a control, a word, a default, a colour, a dot. - Anything expensive to reverse: data shape, permissions, naming, anything public. - A rule the founder states in conversation ("no glow anywhere", "3 dots means nothing"). A change without its record is not finished. That is written into `docs/ux/README.md` and into the repository's `CLAUDE.md`. ## The template Copy `docs/ux/decisions/_template.md`. Every heading is required; "n/a" is allowed only where the decision is a rule with no screen. ```markdown # NNNN · Title - **Status:** Accepted | Draft (rationale to confirm) | Under review | Superseded by NNNN | Removed - **Date:** YYYY-MM-DD - **Source:** who said or decided this, and where it is recorded ## Problem Who has it, in what situation, in their own words where we have them. ## Why this needs to exist What happens to the person if we do nothing. ## Alternatives we considered At least two, with why each was not chosen. ## Decision What we built or chose, in plain words. ## Why this is the best solution Tied to the principles. Name the principle. ## Every element, and what it means The screen's parts, including dots, badges, counts and colours. ## What would make us remove it The evidence that would tell us this is not helping. ## Open questions and history Dated one-line notes; what changed and why. ``` ### What each part is for | Part | Write | Avoid | |---|---|---| | Title | The decision as a plain sentence: "Issue the call sheet: numbered, frozen revisions" | A feature name: "Call sheet v2" | | Source | The founder's words in quotes, a commit, an audit file | "Team decision" | | Problem | The person, the situation, what they experienced | The solution in disguise | | Alternatives | Two or more real options and why each lost | A straw man | | Every element | Each dot, badge, count and colour with its meaning; also add them to `docs/ux/element-register.md` | "Standard UI" | | Remove it | Observable evidence | "If users don't like it" | | History | Dated lines, commit hashes, what a supervisor found and what was not fixed, with the reason | Rewriting earlier lines | ## How records are numbered - **Always** take the next free four-digit number after the highest in the folder, and name the file `NNNN-short-slug.md`. - **Never** renumber or reuse a number. Commits, code comments and other records cite them. The folder already holds two records numbered 0019, 0029, 0041 and 0043, written by parallel sessions; they stay as they are, and you cite them by number and title. - **Always** add the record to `docs/ux/decisions/README.md`. - A record that replaces another sets the old one to "Superseded by NNNN" and links forward. Nothing is deleted. ## Status | Status | Means | |---|---| | Accepted | The founder agreed it. Build to it. | | Draft | Built or proposed; the founder has not confirmed the rationale or the review ladder has not run. Say so in the status line. | | Under review | Being tested against the mission (for example the writing rhythm, Decision 0008). | | Superseded by NNNN | Replaced; read the newer one. | | Removed | The feature is gone; the record stays so nobody brings it back by accident. | ## Four real records, summarised ### 0016 · Phone: content first, a one-line header, one FAB **Problem.** On a phone the Outline showed a two-line header, account and comments icons, then three rows of controls before any writing; the writer's work got about 20% of the screen. **Founder's words:** "80% of the page is non-writing stuff … no breadcrumb, just a back button … comment, account and edit under one FAB at the bottom". **Rejected:** a two-line title (the story name is already known), a breadcrumb on phone (no room, and back is all a phone needs), account and comments in the header (occasional actions, not navigation). **Decision:** one 44px line (back, one-word title, labelled Menu); Comments, Quick note and Account in one floating button at the bottom corner; a screen's tools collapse so content starts by y≈120. **Remove it if** writers cannot find Comments or Account in testing. **History worth reading:** the fix round got Outline content from y≈392 to y≈222 at 375 wide and says plainly that the y≈120 goal is not met yet. ### 0020 · Issue the call sheet: numbered, frozen revisions **Problem.** A second AD edits the sheet all night, prints it, and the crew holds a paper that no longer matches the screen; nobody can say which version went out. **Rejected:** locking the sheet when issued (stops the person fixing a call time at midnight), storing only an `issuedAt` stamp (says when, not what), jsPDF export (Latin-only; Indian names break). **Decision:** "Issue Rev N" freezes a numbered copy; the working draft stays editable and says "Matches Rev N" or "Changed since Rev N"; issued copies print, save as PDF and download as CSV. **What makes it a good record:** a full review-ladder section listing what was fixed, what was not fixed and why (two devices issuing in the same minute can still both write Rev N), and the warning that the app change must not ship before its rules. ### 0042 · Sharing by film role, in one panel, safe by default **Problem.** An owner met three tabs, 56 permission buttons and a default of edit everything; Kwark sends no email, so nobody invited was ever told. **Founder's words:** "the sharing module UX and UI both are very very bad". **Rejected:** plain levels like a document editor (a producer thinks "the DOP", not "edit on Look Book: colour"; kept underneath as the fine-tune), restyling the grid. **Decision:** one panel; roles Reader, Actor, Co-writer, Director, Producer, Camera, Crew and Custom; new people are Readers; the request link is off until turned on; Copy invite message instead of pretending to send mail. **Remove it if** owners still choose Module by module for most people. ### 0044 · Unified breadcrumb and phase and module dropdowns **Problem.** Write and Prepare to shoot drew breadcrumbs two different ways, one with centred menu rows. **Rejected:** a local CSS patch (leaves two systems), one mega-switcher (hides where you are). **Decision:** one `Breadcrumb` component styled only by `--k-crumb-*` tokens, one trail builder, `Home ▸ Project ▸ Phase ▾ ▸ Module ▾`, and named exceptions (the screenplay editor, the shot listing workbench, phones, Home). **Enforced by** `tests/breadcrumb.test.cjs` and `tests/design-system.test.cjs`: a record whose rule is checked by a test cannot drift. ## The element register The dot rule from `docs/ux/how-we-decide.md`: every small thing on screen that carries meaning (a dot, a badge, a count, a colour, an edge, an icon with no label) has a row in `docs/ux/element-register.md` saying what it means, when it appears, what the person is meant to do about it, and why it earns its place. A dot with no reason is removed. ## Rules - **Must** write or update a record for every change a person can see or feel, in the same change. - **Must** quote the founder's own words in Source and Problem when the decision came from him. - **Must** list at least two alternatives with the reason each lost. - **Must** say what evidence would make us remove it. - **Always** append dated history lines; never rewrite old ones. - **Always** write what a supervisor found that was not fixed, and why. - **Never** mark a record Accepted that the founder has not agreed. - **Never** cite a principle without naming it. **Do:** "What would make us remove it: owners still choosing Module by module for most people." **Don't:** "What would make us remove it: negative feedback." ## AI readiness test **Task:** You moved the "Keep a restore point" command from Edit to File. Write what the record needs. **Give the agent:** This page, Decision 0015, the template. **Constraint:** Do not create a new number if an existing record covers it. **A reliable answer:** - Adds a dated history line to 0015 rather than a new record - Says what the writer experienced before and after - Names the principle (one home per command) - Updates any element or shortcut it touched --- # Discovery > How Kwark decides what is worth building for a person: who it is for, the real job, the assumptions that could be wrong, and the smallest test, without inventing research it does not have. Source: https://kwark.space/designSystem/method/discovery ## What discovery is for at Kwark Discovery answers one question before anything is designed: is there a real person with a real problem here, and what is the smallest thing that helps them? Kwark's principle 2 is "a problem before a feature": copying a competitor is never a reason, and a feature that cannot name the person and the situation in one sentence does not start. Kwark has no research team and, today, no panel of users to interview on demand. That makes honesty about evidence part of the method, not a footnote. ## Who Kwark is for These are the people every decision is tested against. They come from the founder's brief and the mission, not from a survey. | Person | Their situation | |---|---| | The part-time filmmaker | A student or working professional who wants to make films but cannot do it full time. Writes after a ten-hour shift. | | The first-time writer | Unsure, sometimes afraid. Needs the way to begin to be obvious and one step away. Students from 13 years old are included. | | The indie production | A short timeline and a short shoot. Accuracy and time saved matter more than features. | | The crew on the day | A 1st or 2nd AD, a DOP, an actor, on a phone with bad signal, holding a printed call sheet. | | The writer in India and beyond | Writes in Tamil, Hindi or another Indian script; works under rules that differ by country. | The state Kwark protects for all of them is **calm**: nothing competes with the page, nothing counts, grades or nags, every state says the work is safe. ## The discovery steps 1. **Name the need in one sentence.** Who, in what situation, blocked by what. The principle's own example: "indie shoots are short, so every scene shows its runtime and the timeline shows talk against action." 2. **Say what happens if Kwark does nothing.** If the answer is "nothing much", stop. 3. **Find the real job.** What is the person trying to get done, in their words? A second AD's job is not "manage call sheets"; it is "make sure 23 people arrive at the right place at 06:30 with the right pages". 4. **Name the paper.** If the film industry already has a paper artefact for this job (a marked-up script, a stripboard, a call sheet), that is the shape of the answer. See [Specs and handoff](https://kwark.space/designSystem/method/specs-and-handoff.md). 5. **List the assumptions that could be wrong** across value (do they want it?), usability (can they use it?), feasibility (can we build it on the free tier?) and viability (should Kwark do it at all, given its rules?). 6. **Pick the riskiest one and the smallest test.** A mock-up shown to the founder, a built screen in the preview, a role simulation, a single real shoot. Write what result would change the plan. 7. **Decide, and record why.** Two or three options with costs; recommend one; the founder decides anything expensive to reverse. ## Evidence: what counts and how to say it - **Must** say where every claim about people comes from: the founder's words, a real shoot, a support message, a code audit, a simulation. - **Never** invent research, metrics, users or quotes. No "users told us", no "studies show", no made-up percentages. - **Never** present an agent's role simulation as user research. It is a rehearsal that finds where a design breaks, labelled "simulated". The review ladder uses them on purpose (a 1st AD, an actor, a line producer, a writer in Tamil), and their findings are design defects to check, not evidence of what people want. - **Always** write the honest limit beside a claim: "checked at 375 wide with touch emulation; not on a real phone", "read from code; nobody ran it on a device". - **Always** put the founder's own words in quotes when they are the source. ### The audit as discovery The 17 October 2026 audit (`docs/ux/audit/SUMMARY.md`) is a good model of honest discovery from code. It opens: "All findings are from reading code; nobody ran the app on a device. Verify each before fixing." It found real problems a writer would meet (the idle curtain that would blank a pitch after 60 seconds, a UTC "today" that gave India yesterday before 05:30, Cmd+S making a snapshot nobody asked for) and ranked them by what they cost the person, not by how hard they were to fix. ## Asking few questions, then deciding Discovery with the founder is not an interview. He answers in feelings and outcomes; he tires of questions with obvious answers. - **Must** ask two or three questions at most, and only those that change what gets built. - **Always** state your call for anything with an obvious default, in one line, and record it. - **Always** show something (a mock-up, a screen) and let the reaction do the work. A good question: "Should the sample film open in the visitor's library, or only in a pop-up?" A question that should have been a decision: "Should the button say Start or Begin?" ## When a real person is available When the founder has a producer meeting, a shoot, or a writer friend, discovery uses them well: - Ask about the last time, not the future: "Tell me about the last call sheet you sent." Not "Would you use a call sheet tool?" - Ask what they tried and what they did not love about it. - Never pitch during the conversation. Write down their words exactly. - Watch them use the real screen, on their own phone if possible. Real-device and screen-reader checks need a person; agents cannot do them from here. ## Rules - **Must** name the person, the situation and the problem in one sentence before naming a feature. - **Must** say what happens to the person if Kwark does nothing. - **Never** treat "a competitor has it" as the need. - **Never** fabricate research, quotes or numbers, or present simulations as research. - **Always** test the riskiest assumption first, with the smallest test that could change the plan. - **Always** run the need through Kwark's rules: no judgement, nothing social, structure optional, free tier. **Do:** "Need: a second AD reprints the call sheet at 2 a.m. and nobody can say which version the crew holds. Source: Wave 3 plan and the call sheet review." **Don't:** "Need: 78% of ADs want version control." (No such survey exists.) ## AI readiness test **Task:** Decide whether Kwark should add a cast availability calendar. **Give the agent:** This page, Product skills, the mission, Decision 0043 (calendar for artists). **Constraint:** No invented evidence; label any simulation. **A reliable answer:** - States the need in one sentence with a named person and situation - Lists value, usability, feasibility and viability assumptions - Picks one smallest test and the result that would change the plan - Labels role simulations as simulated - Checks reads and writes against the free tier --- # Product skills > The product-management and design skills Kwark uses, what each is for, when it is the right tool, and how to run it with an AI agent so the answer stays true to Kwark's rules. Source: https://kwark.space/designSystem/method/product-skills ## What these are The founder keeps a library of skills in `~/.claude/skills/`: packaged instructions an AI agent loads to run a product or design method the same way each time. They come from several sources (a product-management fellowship he took in 2025, published PM and design skill sets) and they are generic. This page says which ones Kwark uses, for which step of the [method](https://kwark.space/designSystem/method.md), and what Kwark changes about each so that a generic method gives a Kwark answer. A skill is a tool, not an authority. Where a skill and a Kwark decision record disagree, the record wins. ## Download the Kwark workflows The original methods below describe the founder’s working library. The downloadable [Product workflows](https://kwark.space/designSystem/agents/skills.md#product-workflows) adapt that process for a team using the public system. Each skill names its inputs and the result it should leave. They cover framing, opportunity mapping, assumptions, prioritisation, specification, synthesis, measurement and release checks. ## The spine: one chain The `nextleap-pm` skill distils the fellowship into one chain that every deliverable walks in order: **business outcome, product outcome, the person, the problem, a hypothesis, several distinct solutions, prioritise, design (flow, wireframe, prototype), spec, metrics and experiments.** Its first rule is Kwark's too: never start from a solution. "It's impossible to judge an idea if you don't understand the problem it solves." Kwark's [UX before build](https://kwark.space/designSystem/method/ux-before-build.md) is this chain with the founder's agreement inserted after the design step. ## The skills, by step ### Frame the problem | Skill | For | Kwark uses it when | |---|---|---| | `pm-problem-statement` | Who is blocked, what they are trying to do, why it matters, how it feels | Writing the one-sentence need at the top of a spec | | `prod-problem-validation` | Whether a problem is worth solving: frequency, intensity, workarounds | A request arrives with no named person | | `pm-jobs-to-be-done`, `prod-jtbd-analysis` | The job a person hires a product for, pains and gains, the forces for and against switching | Finding the real job behind a feature request ("make sure 23 people arrive at 06:30", not "manage call sheets") | | `pm-customer-journey-map` | Stages, actions, thoughts, feelings across a flow | Walking a multi-screen journey, such as a guest who imports a film and reloads (Decision 0034) | | `pm-proto-persona` | A working profile before deeper validation | Rarely; Kwark's people are already named on [Discovery](https://kwark.space/designSystem/method/discovery.md). Label any persona as a proto-persona, not research | ### Map the options | Skill | For | Kwark uses it when | |---|---|---| | `discovery-opportunity-solution-tree`, `pm-opportunity-solution-tree` | From one outcome to the opportunities under it, the solutions for each, and the tests | A broad ask ("make Home calmer") needs breaking into separable problems | | `discovery-brainstorm-ideas-existing` | Ideas from PM, designer and engineer viewpoints | Three distinct solutions are needed for a record's Alternatives section | | `pm-user-story-mapping` | Activities, steps and release slices along the journey | Cutting a big feature (series and universes) into slices that each ship safely | ### Find what could be wrong | Skill | For | Kwark uses it when | |---|---|---| | `discovery-identify-assumptions-existing` | Risky assumptions across value, usability, viability and feasibility | Before any build longer than a day | | `discovery-prioritize-assumptions` | An impact by risk grid and an experiment for each | Choosing which assumption to test first | | `discovery-brainstorm-experiments-existing`, `pm-pol-probe` | The cheapest test that could prove an assumption wrong | Choosing between a mock-up, a preview build and a role simulation | | `discovery-interview-script`, `prod-user-interview` | Interview questions about past behaviour, no pitching | The founder has a producer meeting or a shoot coming | | `discovery-summarize-interview`, `anthropic-design-research-synthesis` | Turning notes into needs and actions | After a real conversation, with the person's words kept exact | ### Decide what goes first | Skill | For | Kwark uses it when | |---|---|---| | `discovery-prioritize-features`, `pm-prioritization-advisor` | Ranking a backlog by impact, effort, risk and fit | An audit produces 40 findings (the 17 October audit ranked its top ten by what each cost the writer) | | `prod-scope-cutting` | Fixed time, variable scope | A feature has grown past its appetite | | `prod-bet-sizing` | One-way and two-way doors; how much a bet is worth | Anything expensive to reverse: data shape, permissions, naming | ### Specify and hand off | Skill | For | Kwark uses it when | |---|---|---| | `anthropic-pm-write-spec`, `pm-prd-development`, `prod-prd-writing` | A spec with goals, non-goals and acceptance criteria | Writing the proposal that becomes the decision record. Use Kwark's parts list on [Specs and handoff](https://kwark.space/designSystem/method/specs-and-handoff.md) | | `anthropic-design-design-handoff` | Layout, tokens, props, states, breakpoints | Handing a designed screen to a builder agent | | `pm-user-story` | Stories with acceptance criteria | Writing the tests a fix must pass | ### Position and compare | Skill | For | Kwark uses it when | |---|---|---| | `anthropic-pm-competitive-brief`, `prod-competitor-analysis` | Feature matrices and gap analysis | A competitor review. Filter it through [Competitors are the floor](https://kwark.space/designSystem/method/competitors-are-the-floor.md) | | `pm-positioning-statement`, `prod-product-positioning` | Who it is for, the problem, the category, why it differs | Public pages such as `/why` and `/info`, where every sentence is a promise | ### Review the design and the words | Skill | For | Kwark uses it when | |---|---|---| | `anthropic-design-design-critique`, `ui-design-review` | Hierarchy, consistency, usability | The UI and UX supervisor rungs of the review ladder | | `anthropic-design-accessibility-review`, `a11y` | WCAG contrast, keyboard, targets, screen reader | Every UI review; the result lists P0, P1, P2 with criteria | | `anthropic-design-design-system` | Naming, hard-coded values, documenting a pattern | Auditing a screen for raw colours or adding a pattern to this site | | `anthropic-design-ux-copy`, `ux-writing` | Buttons, errors, empty states, toasts | Writing every string in a spec | | `ux-researcher-designer` | Personas, journeys, usability test plans | Planning a usability session with a real person | ## What Kwark changes about every skill Generic product methods assume a growth business with a research team. Kwark is a calm place to write with one founder. Tell the agent this before it runs any skill. - **Never** let a skill's metrics become engagement targets. No daily active streaks, return-visit goals, notifications to bring people back, or public counts (Decision 0001). Kwark measures whether work is safe and whether people can do their job. - **Never** let a brainstorm propose AI scoring, coverage or feedback on the writing (Decision 0002), or coaching prompts (Decision 0004). - **Never** let a synthesis invent users, quotes or numbers. If there are no interviews, the skill's output says so. - **Never** run an A/B test on writers' work or split people into groups that see different safety behaviour. Kwark's tests are mock-ups, preview builds, role simulations and single real sessions. - **Always** estimate reads, writes, listeners and file sizes for the actual action and expected audience. Use the project’s current service limits and cost constraints. - **Always** keep competitor names out of anything published (Decision 0045). - **Always** finish with a decision the founder can make in one message: two or three options, a recommendation, and its cost. ## How to run a skill with an agent 1. **Load the context first.** Give the agent the project’s mission, the current handoff and relevant decision records. For a team starting from this site, use [Principles](https://kwark.space/designSystem/foundations/principles.md), the closest [kit](https://kwark.space/designSystem/kits.md) and its own source artefacts. 2. **Name the skill and the step.** "Use discovery-identify-assumptions-existing for the call sheet crew link. We are at step 5 of discovery." 3. **Give the Kwark constraints in the prompt** (the list above), not afterwards. 4. **Ask for the output in Kwark's shape**: a need sentence, options with costs, a recommendation, open questions that change the build (three at most). 5. **Review it as the founder would.** Does it count, grade or nag? Does it claim evidence it does not have? Is it phone first? 6. **File it.** Proposals in `docs/ux/proposals/`, reviews in `docs/ux/audit/`, the decision in `docs/ux/decisions/`. > **For agents:** When you run a product or design skill for Kwark, state at the top which skill you used and which step of the method it serves, and list any of the skill's defaults you overrode because of a Kwark decision record. **Do:** Run `discovery-prioritize-assumptions` on the crew link and conclude: "Riskiest: an anonymous link exposes contact numbers. Test: security review of the rule before any UI." **Don't:** Run a metrics skill and propose "daily active writers" and a streak to raise it. ## AI readiness test **Task:** Use an opportunity solution tree to plan "help writers finish their first draft". **Give the agent:** This page, Discovery, Decisions 0001, 0002, 0004, 0008. **Constraint:** Kwark's constraints stated before the tree. **A reliable answer:** - The outcome is about the writer's progress on their own terms, not engagement - No streaks, scores, public counts or AI feedback appear as solutions - Each solution names the artefact it feeds or the fear it removes - Ends with the riskiest assumption and the smallest test, labelled honestly --- # Review and quality > What "done" means for a Kwark change: built from the system, looked at in screenshots, reviewed by separate supervisors, tested, inside the free-tier budget, then shipped to main one feature at a time. Source: https://kwark.space/designSystem/method/review-and-quality ## Why "it works" is not done `docs/ux/definition-of-done.md` was written on 17 October 2026 after the founder found the phone menu header had shipped with plain text, no icons, no chevrons and wrong alignment. He is an expert UI and UX designer; he cannot judge engineering or security work directly, so a visible gap in his own field makes him doubt everything else. Quality you can see is how trust in the rest is earned. ## The gate Every UI change, no exceptions. 1. **Built from the system.** Shared `Button`, `TextButton`, `IconButton`, `Sheet`, `ListRow`, `Segmented`, `PageHeader`; tokens only; icons 14, 16 or 20; 44px tap targets on phones. 2. **Every control says what it is.** A word, or a labelled icon. Nothing that is only "⋯". Anything that opens something has a chevron. 3. **Looked at, not just run.** Screenshots at 1440, 768 and 375 (and 320 for headers), zoomed in. Check alignment, clipping, centring and states: hover, focus, checked, disabled. 4. **Two supervisors before it is called done.** A UI supervisor (design-system compliance, alignment, spacing, icons, labels, contrast in every room, clipping) and a UX supervisor (walks the journeys, plain names, one home per command, nothing lost from the old design, shortcuts that are real). 5. **Defects fixed, then re-checked.** A finding is never marked "not needed" without a written reason in the decision record. 6. **Record updated; typecheck, tests and build green.** ## The review ladder Added 18 October 2026 as a founder rule: every feature or update, even the smallest UI, goes through each rung in order. Reviewers are separate agents, review-only, who write their findings to `docs/ux/audit/review--.md`. The builder fixes; the same reviewer re-checks. | Rung | Reviewer | Looks for | |---|---|---| | 1 | Role simulation | Agents play the real users and try to do their job: a 1st AD, 2nd AD, actor, DOP, line producer, a crew member on a phone with bad signal, a screenwriter, a writer in Tamil | | 2 | Ponytail review | The smallest complete change, reuse, no dead code, tests present | | 3 | Database | Reads and writes per action, document shape and size, no unbounded lists or listeners, no base64 images stored, old data still works, offline behaviour | | 4 | UX supervisor | The journeys, the words, nothing lost | | 5 | UI supervisor | The gate above | | 6 | Security | Who can read or write what, rules impact, injected text, share links, personal data, guest mode | | 7 | Founder supervisor | Judges as the founder would: calm, safe, never judging or scoring, nothing social, structure optional, plain words, cost. Would he trust this in front of a producer tomorrow? | | 8 | Engineer handoff | A new engineer could take it over: honest types, clear names, tests that describe behaviour, the record says why | Roles join early, not only at the end: simulate before building to find what the feature must do, review after. Creative work (look, wording, layout) is done or reviewed by an Opus-level agent at high effort. The call sheet issue (Decision 0020) shows the ladder working: the reviews caught a false "Edited since" alarm, moved the frozen-copy builder into a tested file, added a "Draft, not issued" stamp to printed drafts and guarded the CSV against formula injection, and listed plainly what was not fixed and why. ## Accessibility check Part of every UI review, not a separate project. - **Must** reach 4.5:1 for text and 3:1 for icons, field borders and the focus ring, in light, dark and all five writing rooms. - **Must** reach every command by keyboard, with a visible focus ring. - **Must** give every icon-only control an accessible name that includes its object. - **Must** use 44px targets wherever the pointer is coarse. - **Always** check text zoom to 200% and reduced motion. - **Always** say plainly that real-device and screen-reader checks need a person, and list them as open until one has done them. See [Accessibility](https://kwark.space/designSystem/foundations/accessibility.md). ## Tests - `npx tsc --noEmit`, `npm test` and `npx vite build` green before a change is called done. - The build's design checks fail on raw hex, raw pixel font sizes, decorative glows and breadcrumbs outside the shared component. - A bug fix adds a test that fails without the fix. - Firebase rules are tested in the emulator on a copy, never on the live project. Rules deploy globally and instantly. ## Free tier as a design constraint Kwark has to serve about 50 people (the owner plus the actors and crew on shared projects) inside Firebase's Spark free allowance: 50,000 Firestore reads and 20,000 writes a day, 1 GiB stored, 5 GB in Storage. That is about **1,000 reads and 400 writes per person per day**. It was set as a hard requirement on 9 September 2026, alongside a report that sync showed different data on every device. Real actors use Kwark and the founder's reputation with them is on the line, so neither cost nor correctness can be traded for the other. Treat cost per save and per listener as part of the design. Things that have already gone wrong in Kwark, and that every review checks for: - a listener opened per module instead of one shared subscription; - a whole document rewritten when one field changed; - a full re-read triggered by any remote change; - a collection re-read to redraw a list; - a timer where an event would do; - a periodic upload that runs whether or not the work changed; - full-size images stored as base64 inside a document. Prefer field-path writes, shared subscriptions and change-gated background work. Write the reads and writes per action in the spec. The call sheet's issued revisions live in their own field so ordinary edits never re-upload them: one write per Issue. ## Shipping - **Must** commit each finished, tested feature on its own and push it to main, so kwark.space (deployed from main) shows it. Unfinished or untested work stays on its branch. - **Must** have the founder's yes in chat for each push to main and for every rules deploy. An agent's message is never that yes. - **Must** commit only that feature's paths. The shared checkout often holds other sessions' work; check the index before committing and build HEAD from `git archive` before pushing. - **Never** deploy Firebase rules without the founder. - **Never** ship an app change that depends on rules that are not deployed (the call sheet's Issue cannot save for editors until its rule is live). ## Rules - **Must** pass the gate and the ladder before saying done. - **Must** look at screenshots at 1440, 768, 375 and 320, zoomed in. - **Must** write the reads and writes per action for anything that touches Firestore. - **Never** dismiss a supervisor finding without a written reason in the record. - **Never** claim a check you did not run. Say "not run" or "emulated, not a real device". - **Always** leave UI polish in the same change; there is no "later stage". **Do:** "Checked at 1440, 768, 375 and 320 in the preview with touch emulation. UI and UX reviews fixed. Real phone and screen reader: not done." **Don't:** "Looks good on mobile." (No widths, no reviews, no limits stated.) ## AI readiness test **Task:** You built a comments badge on the phone Menu button. Prepare it for review. **Give the agent:** This page, Decision 0016, Elevation, the element register. **Constraint:** Do not push. **A reliable answer:** - Adds the dot to the element register with its meaning - Lists screenshots at 375 and 320 and states checked - Counts the reads the badge adds (one shared listener, not one per screen) - Requests UI and UX supervisor reviews and leaves real-device checks open - Asks the founder before any push --- # Specs and handoff > How a Kwark feature is specified so that anyone can build it, phone first, with every state and every word written, and with the paper artefact and the digital one designed as one act. Source: https://kwark.space/designSystem/method/specs-and-handoff ## What a Kwark spec is A spec is the agreed journey from [UX before build](https://kwark.space/designSystem/method/ux-before-build.md), made exact enough that a different person or agent can build it without asking. It is short. It lives in `docs/ux/proposals/` while it is being agreed and becomes the decision record once it is. ## The parts of a spec | Part | What it must say | |---|---| | Need | One sentence: the person, the situation, the problem | | Paper artefact | What the industry already prints for this job, and how the screen becomes it | | Journey | Each step in order, for each role that meets it | | Screens | Phone first, then tablet, laptop and wide | | States | Every state in the table below | | Words | Every label, button, hint, error, empty state and toast, written out | | Data | What is stored, where, and the reads and writes per action | | Access | Who can see and change it; what a read-only person sees | | Out of scope | What this does not do, named | | Remove it | The evidence that would make us take it out | ## Paper and digital, one act Decision 0005. A crew already works from stripboards, call sheets and breakdown sheets; a table alone is not something a crew will accept on set. For every module bound to the screenplay, Kwark builds the artefact a crew already makes by hand and the thing software can do, as a single act. The founder: "they can break it down conventionally, and also have more structured view, and print them both out as and when needed". | Job | The paper way | Built in Kwark as | |---|---|---| | Breakdown | The AD marks the script pages with coloured pencils, then copies onto a sheet | Select words on the real script page; they underline in the department's colour and the sheet line is written. Either prints. | | Shot list | A lined script: a vertical line down the margin beside the lines a setup covers | Drag down the margin; that is the shot. The list and the coverage gaps follow from it. | | Schedule | Paper strips on a board | Strips on a board, already | | Call sheet | A printed one-page sheet | A paper facsimile that issues numbered revisions with PDF and CSV (Decision 0020) | - **Must** name the paper artefact a feature replaces before designing it, and make that the interaction, not a view beside it. - **Must** make it print. See [Print and export](https://kwark.space/designSystem/patterns/print-and-export.md). - **Never** ask a director to design a schema before saying where the camera goes. That is what made the old shot list "weird". ## Phone first Draw at 375 wide first, then check 320. Kwark's screen spec (`docs/ux/screens-and-input-spec.md`) names four rooms by situation, not by pixels: | Room | When | Layout | |---|---|---| | Phone | Narrower than 768, or a touch screen shorter than 520 (a phone on its side) | One column, one 44px header, bottom sheets | | Tablet | 768 to 1023 | Desktop chrome, narrower rail, panels over the page | | Laptop | 1024 to 1439 | Full chrome, one panel beside the page | | Wide | 1440 and up | As laptop; the script never stretches past its page width | Input is separate from size. Ask the pointer, not the width: fingers get 44px targets and nothing hover-only or drag-only; a mouse may get hover tips and 32px targets; the keyboard is always supported. A tablet with a keyboard is both. - **Must** use the shared compact query in the screenplay (`useEditorLayout()`), never a bare `max-width: 767px`, so a phone held sideways gets the phone layout. - **Must** start the person's content by about y = 200 on a phone, aiming for y≈120 (Decision 0016). ## Every state A spec that shows only the full, happy screen is not finished. | State | Example from Kwark | |---|---| | Empty | "No call sheets yet. A call sheet is made for each shooting day, and the days are built from the screenplay's scenes." | | Loading | "Opening the script…" | | Saved | "Saved", then the word steps back after a moment | | Offline | "Saved on this device" | | Not downloaded | "This screenplay has not downloaded to this device. Nothing will be saved until it does." | | Conflict | "This screenplay was changed in another session. Your edits are kept on this device and have not overwritten it." | | Error | One calm sentence from `friendlyError()`: what happened, that the work is safe, what to do | | Read-only | What a Reader sees, and why a control is disabled, written on the page | | No access | "{Owner} hasn't shared {module} with you." | | Too much | 400 scenes, a 90-character location name, a Tamil character name | ## Words are part of the spec - **Must** write every string in the spec. Copy is designed, not filled in at the end. - **Always** use one word for one thing through the flow: Issue, Issued, Rev 3. - **Always** read each sentence aloud to a nervous writer (the honest-copy test). See [UX writing](https://kwark.space/designSystem/foundations/ux-writing.md) for the voice. ## Handoff between people and agents Kwark's work moves between Claude, Codex, Antigravity and the founder, often mid-task. A handoff is part of the work, not a courtesy. - **Must** update the State section at the bottom of `docs/ux/HANDOFF.md` whenever work stops: what was done, where it stopped, the next step. - **Must** append an entry to `~/AIContext/log.md` in the form `## YYYY-MM-DD HH:MM — tool/account — project`. - **Must** say what was verified and how ("checked at 1440, 768, 375 and 320 in the preview; not on a real phone"), and what was not. - **Always** include a prompt the next agent can paste to resume, with the paths it must read first. - **Never** leave work only in chat. See also [Handoff for agents](https://kwark.space/designSystem/agents/handoff.md). ## Rules - **Must** include need, paper artefact, journey, screens, states, words, data, access and out-of-scope in every spec. - **Must** draw the phone layout first. - **Must** specify the empty, loading, offline, error and read-only states. - **Never** spec from `DESIGN_SYSTEM.md` in the main checkout: it is stale. The September stylesheets and `styles/tokens.css` are the look. - **Always** write the reads and writes per action beside the data. **Do:** "Breakdown: select words on the page; they underline in Props' colour and the line appears on the breakdown sheet. Both print." **Don't:** "Breakdown: a table with columns for scene, category and item." ## AI readiness test **Task:** Write the spec for a costume continuity sheet. **Give the agent:** This page, Decision 0005, Print and export, Review and quality. **Constraint:** Phone first; every state; every string. **A reliable answer:** - Names the paper artefact (the continuity sheet with photos per scene and character) and makes it the interaction - Lists empty, loading, offline, error and read-only states with real copy - Draws 375 before desktop - Gives reads and writes per action and stores photos in Storage, not base64 in a document --- # Structure, not teaching > Every field in Kwark feeds a real artefact a person can use. Kwark never coaches, quizzes or explains film theory, and every piece of structure can be switched off. Source: https://kwark.space/designSystem/method/structure-not-teaching ## Two rules that work together **Structure, not teaching** (Decision 0004). Kwark is for students and working professionals who want to make films but cannot do it full time. They need working structure, not film school. On 17 September 2026 the founder said: "structure is our usp, not teaching them. that's why pre production must be more comprehensive." **Structure is always optional** (Decision 0003). Some writers want an outline tied to the page; some want an empty page. On 8 September he said beat-to-screenplay "must be flexible and must not force user to use structure unless they want to, and this can be switched off whenever they want." Together: Kwark gives people more structure than any other tool, and asks them to use none of it. ## The artefact test For every field, ask: **what real artefact does this end up in?** A list, a sheet, a date, a cost, a page that prints. If the answer is "it helps them think", the field is coaching and it goes. | Field | Ends up in | Verdict | |---|---|---| | A character's age | The character page, the cast list, the casting brief | Keep | | A scene's day or night | The scene heading, the stripboard strip colour, the call sheet | Keep | | A location's cost per day | The budget | Keep | | "Name the feeling we force them to endure" | Nothing | Remove | | A 0 to 100 slider for "tension" | Nothing a crew can use | Remove | | A preset explaining what a push-in "means" | Nothing | Remove | The modules the founder disliked and that were removed under this record: the Director's Manifesto prompts, Camera Language's emotional arc, an Enneagram quiz, "Engine of…" text, tension sliders, camera "meaning" engines, an Idea "Conviction" percentage and Outline "Finder" trophies. ### A recent case Empty cards in the outline's Writing view once showed questions by story position, such as "What does an ordinary day look like before anything changes?". They were coaching inside a field, shipped before the rule was written. On 4 November they were removed: an empty card now says "Add words…". Nothing the writer had written was touched. Whether to bring them back as an opt-in is an open question for the founder, recorded in 0004. ## Comprehensive means every department, not more explanation "Structure is our USP" is a promise of depth: pre-production covers each department's real prep (breakdown, shots, schedule, call sheets, budget, paperwork, costume, camera and light). It is never a promise to explain how those jobs are done. A second AD knows what a call sheet is; Kwark's job is to make one that is right. ## Understanding is about the story The writing phase describes the story, not the production. The character tab once called "Casting Sheet" is now **Characteristics**: age, occupation, distinctive features and appearance are facts the writer decides long before anyone is cast. A real casting sheet (availability, representation, union standing) is a different document about a different person and lives in Cast & Crew in Prepare to shoot. - **Always** ask whether a new field describes the story or the production. Production goes to Prepare to shoot. - **Never** assume one country's industry: unions, guilds, contracts and paperwork are country-specific. ## Optional, all the way down Every structure-aware feature is opt-in and can be switched off at any time: the beat map, the structure rail, act assignment, breakdown tags, writing insights, the timeline. - **Must** put every structure-aware editor feature behind a switch. In the screenplay these live in Settings, labelled "This project", for example **Map the outline onto the script** and **What the page shows**. - **Must** default a structure feature to off for a script with no linked outline. - **Must** leave nothing behind when a feature is off: when the beat map is off, the panel shows only the switch, not an outline underneath. - **Never** block writing on a missing beat. Acts land in a scene with no beats written in them, in any order; writers write act 1, then 3, then 2. - **Never** create outline entries automatically without asking. - **Always** let the writer choose the level of the outline the page shows, offering the levels their outline actually has, with the top level recommended. A switch that cannot turn a feature fully off is a bug (Decision 0003). ## Writing labels without teaching - **Always** label a field with the plain noun a crew uses: "Call time", "Cost per day", "Day or night". - **Always** use a hint, if any, to say where the value goes: "Appears on the call sheet." Never to say why it matters to the story. - **Never** phrase a label as a question to the writer. - **Never** add a "Learn more" lesson beside a field. Help that explains Kwark's own controls is fine; help that teaches filmmaking is not. **Do:** **Cost per day.** Hint: "Goes to the budget for every day this location is booked." **Don't:** **What does this place cost your story?** Hint: "Locations carry emotional weight. Consider…" **Do:** When the beat map is off, the panel shows one switch: **Map the outline onto the script**. **Don't:** When the beat map is off, the outline still shows underneath in grey "so they know it is there". ## AI readiness test **Task:** Add fields to the Look Book for a film's colour palette. **Give the agent:** This page, Decisions 0003, 0004, 0005, Specs and handoff. **Constraint:** No new coaching copy. **A reliable answer:** - Names the artefact each field feeds (the printed look book, the costume and art department sheets) - Labels are plain nouns with hints that say where the value goes - Nothing is required to save - No "meaning" or mood-score fields --- # UX before build > On any feature that spans more than one screen, walk the person's journey and agree its shape by showing it, before a line of code is written. Source: https://kwark.space/designSystem/method/ux-before-build ## Why this rule exists On 27 September 2026 the founder asked for series and universes to be built. The builder went straight into storage and editor plumbing, and produced a film-to-series conversion and an episodes page that were its own guesses. The founder had to step in twice: a film stays a film, series are new projects, and every season and episode needs its own layer of every module with shared data underneath. His words: "we haven't thought this out for the users, we are just adding features". Building first wasted the work, and it left the founder doing the product thinking. The rule that came out of it is now Kwark's feature process. ## When it applies | Change | What is needed first | |---|---| | A new feature that spans two or more screens | The full process below | | A new screen, panel or sheet | Journey and a shape at phone and desktop size | | A change to navigation, sharing, saving or anything expensive to reverse | The full process, with two or three options and their costs | | A one-screen change with an obvious answer | State your call in one line and build it | | A bug fix or polish | The short version on [Kwark method](https://kwark.space/designSystem/method.md) | ## The process 1. **Is it actually needed?** One sentence: who has the problem, in what situation, and what happens to them if Kwark does nothing. If the only reason is a competitor, stop. 2. **The journey.** Write how each kind of person moves through it: where they come from, which screens they see, what they do, where they can go wrong, how they get back to writing. Name every kind of person: the owner, a co-writer, an actor with read access, a guest with no account. 3. **Show it.** A wireframe, an HTML mock-up or a built screen in the preview. Phone first (375 wide), then desktop. Include the empty, loading, error and offline states. 4. **Agreement.** The founder confirms the journey and the shape. Open questions that change what gets built are asked. Obvious defaults are decided and stated. 5. **Build**, in small steps that each ship safely. ### Agree by showing, not by interviewing The founder answers in feelings and outcomes ("excited to explore what the app can do for them", "content with the work they have done"), not in specifications. On 11 November he stopped a round of brainstorming questions: "you are asking too many useless questions ... it's not that complicated". A mock-up gets a faster, truer answer than a question does. - **Must** ask only what changes what gets built: two or three questions at most. - **Always** decide anything with an obvious default (what a new project contains, standard behaviour), say it in one line as your call, and record it. - **Always** show something the founder can react to before asking him to choose. ## Three real examples ### The first frame a new visitor sees (Decision 0035) The problem: a new visitor met a four-slide introduction about the philosophy and the name, and the start button was on the last slide. Three mock-ups were drawn and shown side by side: A, the path of a film; B, the sample film as the front door; C, a blank page with the cursor waiting. The founder chose A in one message. The record keeps B and C with why each lost, and names B as the next thing to try if visitors read the five steps as a feature list and do not start. ### Four writer features from one competitor review After a competitor review on 16 October, four ideas were written up in `docs/writer-safety-features-proposal.md`, each with a need check, a journey and a wireframe before anything was built. The outcome: - **Typing in Indian scripts:** needed; all seven scripts at once. - **Writing rhythm on every device:** needed, but no "your year" grid. - **An independent timestamp on proof of authorship:** needed, deferred. - **A beat table compared against target pages:** not built. Drawing it showed a red "drifted" flag judging the writer. It became targets on the timeline instead: a name and an aim in minutes or pages, no red, no verdict. The fourth is the point of the process: the journey turned a copied feature into a better one before any code existed. ### Series and universes The journey that should have come first, and was written after the correction: a writer starts a series as a new project; an existing film joins a universe by moving its characters and locations into shared canon; each season and each episode has its own layer of outline, characters and pre-production; the screenplay shows episodes in more than one dropdown. Only then was storage designed. ## What a journey document contains | Part | What it says | |---|---| | Need | One sentence, the person and the situation | | People | Every role that meets the feature, including guests and read-only collaborators | | Steps | Each screen in order: what they see, what they do, what can go wrong | | States | Empty, loading, error, offline, read-only, conflict | | Phone | What changes at 375 wide and on a phone held sideways | | Paper | Which paper artefact this replaces, and whether it prints | | Cost | Reads and writes per action against the free tier | | Open questions | Only those that change what gets built, with a recommended answer | ## Rules - **Never** write code for a multi-screen feature before the founder has agreed its journey and shape. - **Never** choose a default silently for anything expensive to reverse: data shape, permissions, naming, pricing, anything public. Write two or three options with costs and recommend one. - **Must** draw phone first, at 375 wide, then desktop. - **Must** include empty, loading, error and offline states in the shape you show. - **Always** name the person and the situation in one sentence before naming the feature. - **Always** keep the rejected options and the reason in the decision record. **Do:** Show three mock-ups of the first frame side by side, recommend one, and ask "which one?" **Don't:** Ask the founder eight questions about tone, audience and layout before drawing anything. **Do:** Write the journey for an actor with read access, then design the screen they see. **Don't:** Design the owner's screen and discover after the build that the actor sees a broken one. ## AI readiness test **Task:** The founder says "start building the AI storyboard pack". **Give the agent:** This page, memory note ai-storyboard-pack-and-3d-boards, Decision 0005, Specs and handoff. **Constraint:** No code in this answer. **A reliable answer:** - Notes the pack's journey is not yet agreed and proposes one - Names who uses it (director, storyboard artist) and the paper artefact (a per-scene PDF and image zip) - Keeps generation outside Kwark (an exported pack and prompt, no API cost) - Asks at most three questions and shows a wireframe of the export dialog --- # Kwark method > How Kwark goes from a filmmaker's problem to a shipped screen, the tests every decision passes, and where each step is written down. Source: https://kwark.space/designSystem/method ## What this section is Kwark is a story workspace built by a founder working alone with AI agents. There is no product team to catch a wrong turn in a meeting, so the method has to be written down well enough that a person or an agent who arrives cold can follow it and reach the same answer the founder would. The method has one purpose, taken from the mission in `docs/ux/mission-and-principles.md`: help people who want to write feel calm, begin writing and keep writing, then take the same work into production. Every step below exists to protect that, and every step leaves a file behind. ## The loop A change a person will see goes through six steps, in this order. Bug fixes and polish use the short version at the end of this page. 1. **Is it needed?** Name the person, the situation and the problem in one sentence, from how they actually work. "A competitor has it" is not a reason. Say what happens to the person if Kwark does nothing. 2. **Their journey.** Walk the whole path: where they come from, what they see at each step, what can go wrong, how they get back to writing. 3. **Show the shape.** A wireframe or a built mock-up at phone size first, then desktop, with empty, loading, error and offline states. Count what competes for attention above the fold. 4. **Agreement.** The founder confirms the journey and the shape. Open decisions are asked, never silently defaulted; obvious ones are decided and stated as the builder's call. 5. **Build** in small steps that each ship safely, with tests, through the review ladder. 6. **Record.** A decision record in `docs/ux/decisions/`, every new dot, badge, count or colour in the element register, and the UI map updated if a component was added. The loop is not a waterfall. Step 3 often sends you back to step 1: drawing the call sheet issue panel is what showed that "Issued" was a field nothing ever set. ## The tests every screen passes These come from `docs/ux/how-we-decide.md`. A screen that fails one is changed or dropped, whoever asked for it. | Test | The question | |---|---| | Calm | Looking at it as a nervous first-time writer, does anything count, grade, warn, nag or ask for attention it has not earned? | | Five seconds | Can someone say what this screen is for and what to do next in five seconds? Is the thing they came for in the first 200px on a phone? | | Meaning | Can we say what every element is for, down to the last dot? | | Remove it | What evidence would make us remove this? It is written in the record. | | Work is safe | If this fails, loses connection or is interrupted halfway, what happens to the writing? | | Everyone | Phone, tablet, laptop; keyboard only; screen reader; slow or no network; a script in Tamil; a user in another country. | | Honest copy | Read every word aloud to a nervous writer. No hype, no shouting, no blame, no jargon. | And the empathy checklist, used in every review: who is this for and what were they doing a minute ago; what are they afraid of right now; what is the smallest thing that helps; what are we making them look at that is not their work; what can they not undo. ## The standing rules Some answers are settled and are not reopened by a new feature. Each has a decision record and a page here. - **Kwark is a safe, private place** (Decision 0001). No contests, leaderboards, public counts or comparing badges. Anything social belongs on Bekwarky, a separate site. - **Kwark never judges the script** (Decision 0002). No AI scores, coverage or verdicts, and no percentage that rates the writer. - **Structure is always optional** (Decision 0003) and **structure, not teaching** (Decision 0004). See [Structure, not teaching](https://kwark.space/designSystem/method/structure-not-teaching.md). - **Paper and digital as one act** (Decision 0005). See [Specs and handoff](https://kwark.space/designSystem/method/specs-and-handoff.md). - **Competitors are the floor** (Decision 0006). See [Competitors are the floor](https://kwark.space/designSystem/method/competitors-are-the-floor.md). - **Their work is never at risk** (principle 12). A feature that can lose work is not shipped. - **The free tier is a design constraint.** About 50 people on Firebase's free allowance. See [Review and quality](https://kwark.space/designSystem/method/review-and-quality.md). > **For agents:** Before you build anything a person sees in Kwark, read `docs/ux/mission-and-principles.md`, `docs/ux/how-we-decide.md` and the decision records your change touches. If your change contradicts a record, stop and say which one; do not quietly override it. ## Who does what | Role | Does | Never | |---|---|---| | Founder | Agrees journeys and shapes; decides open questions; says yes to every push to main and every rules deploy | Is asked a question that has an obvious default | | Builder (person or agent) | Finds the need, walks the journey, shows the shape, builds, writes the record | Pushes, deploys rules or picks an expensive-to-reverse option without a yes | | Supervisors (separate agents, review-only) | Role simulation, UI, UX, database, security, founder judgement, engineer handoff | Edit the code they review, or dismiss a finding without a written reason | ## Where it is written down | File | What it holds | |---|---| | `docs/ux/mission-and-principles.md` | The mission, the state Kwark protects, twelve principles with a test each | | `docs/ux/how-we-decide.md` | The order of work, the tests, the empathy checklist, the dot rule | | `docs/ux/decisions/` | One record per decision, numbered. See [Decision records](https://kwark.space/designSystem/method/decision-records.md) | | `docs/ux/element-register.md` | Every dot, badge, count, colour and edge, with what it means | | `docs/ux/definition-of-done.md` | The gate and the review ladder | | `docs/ux/HANDOFF.md` | State for the next person or agent; updated every time work stops | | `docs/ux/audit/` | Audits and supervisor reviews, one file each | | `~/AIContext/log.md` | The cross-tool handoff log; an entry every time an agent stops | ## Short version for bug fixes and polish Say what the person experienced. Fix the cause, not the symptom. Add a test that fails without the fix. If the fix changes what a person sees, add a dated line to the relevant decision record's history. ## The method, step by step - [UX before build](https://kwark.space/designSystem/method/ux-before-build.md): On any feature that spans more than one screen, walk the person's journey and agree its shape by showing it, before a line of code is written. - [Discovery](https://kwark.space/designSystem/method/discovery.md): How Kwark decides what is worth building for a person: who it is for, the real job, the assumptions that could be wrong, and the smallest test, without inventing research it does not have. - [Competitors are the floor](https://kwark.space/designSystem/method/competitors-are-the-floor.md): Parity with other writing and production tools is the minimum. Every plan leads with what none of them does, and a competitor review is how Kwark finds both. - [Structure, not teaching](https://kwark.space/designSystem/method/structure-not-teaching.md): Every field in Kwark feeds a real artefact a person can use. Kwark never coaches, quizzes or explains film theory, and every piece of structure can be switched off. - [Specs and handoff](https://kwark.space/designSystem/method/specs-and-handoff.md): How a Kwark feature is specified so that anyone can build it, phone first, with every state and every word written, and with the paper artefact and the digital one designed as one act. - [Decision records](https://kwark.space/designSystem/method/decision-records.md): Every decision a person can see or feel gets one numbered record that says the problem, the options, why this one, and what would make us remove it. - [Review and quality](https://kwark.space/designSystem/method/review-and-quality.md): What "done" means for a Kwark change: built from the system, looked at in screenshots, reviewed by separate supervisors, tested, inside the free-tier budget, then shipped to main one feature at a time. - [Product skills](https://kwark.space/designSystem/method/product-skills.md): The product-management and design skills Kwark uses, what each is for, when it is the right tool, and how to run it with an AI agent so the answer stays true to Kwark's rules. ## AI readiness test **Task:** The founder says "add a word-count leaderboard for co-writers". Plan the work. **Give the agent:** This page, Decision 0001, Decision 0002, docs/ux/how-we-decide.md. **Constraint:** Follow the loop; do not write code. **A reliable answer:** - Stops at step 1 and names the conflict with Decision 0001 (no leaderboards or public counts) - Asks what problem the co-writers have, in one sentence - Offers a private alternative only if a real need survives (for example a rhythm only the writer sees) - Points social features to Bekwarky --- # AI assistance > 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. Source: https://kwark.space/designSystem/patterns/ai-assistance ## The problem A director has the screenplay of Blank Pages and a five-day shoot. Every prop, costume and location has to be pulled out of 96 pages into a breakdown before anyone can schedule. A machine can do much of that reading. But the same week, other tools offer to score her script, rewrite Mira's dialogue "for impact", and fill the breakdown in one click with forty items she has never seen. The danger is not that a machine is wrong; it is that its guesses become the work without anyone choosing them, and that a tool built for writers starts telling them whether their writing is good. The founder: "right now the industry has not understood how to use AI in scripting, and I want to be mindful". So the question for every feature is not "can a machine do this" but "who is the author afterwards". In Kwark the answer is always the person. ## Kwark's answer Decision 0002 sets the line: **no AI feedback, scores, verdicts or rewrites of the writer's work.** [AI and authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md) sets the stance and the "May" list. This page is the flow: how each permitted kind of help appears, is accepted, is refused and is undone. ### What runs today, said plainly - **There is no generative model in the app.** Nothing in a project is written, rewritten, summarised or scored by a language model. - **Rule-based guesses on the device:** the breakdown's *The script mentions*; the calendar's quick add, which parses "Table read with Meera next Tue 7pm–9pm Sc 4, 7" without a cloud call; screenplay search that reads "mira night exteriors"; phonetic typing for seven Indian scripts. - **One handoff that exists:** **Copy for AI** on a character page, "A guided handoff to your own AI chat." - **One opt-in that sends text out** (Decision 0046): *Smart phonetic suggestions*, off by default, sending only the word being typed to an input service. - **Agreed, not built:** the AI storyboard pack, exported for a tool the person chooses. Never describe more than this as existing. ### The seven kinds of help, and how each behaves | May | In Kwark | The flow | |---|---|---| | Measure | Runtime per scene, talk against action on the timeline | Shown as a fact, never a rating; same calm colours as everything else | | Find | *The script mentions* in the breakdown | Offered one item at a time with its source and reason; **Add** or **Not needed** | | Carry into production | Scenes into strips, cast into the call sheet | Automatic, because it is the writer's own data moving to where production reads it | | Move the writer's words | An outline beat title proposed as a scene heading (pattern, not built) | Marked with a revision mark until accepted or edited | | Convert typing | "naan ingey irukken" typed in Roman becomes Tamil | The Roman word shows under the caret; Space writes it in; Esc keeps it Roman, and that choice is remembered | | Read aloud | Table reads with the browser's voices | A performance of the text as written | | Hand off | Copy for AI; the storyboard pack | The person sees what travels, copies it, and pastes it where they choose | ### Find: suggestions the person accepts one by one The breakdown's suggestion list is the model for anything a machine finds. Build it with the [suggestion panel](https://kwark.space/designSystem/components/suggestion-panel.md): 1. **A heading that names the source:** "The script mentions". 2. **A line that says nothing has happened:** "Read off the page, never assumed. Nothing here counts until you say so." 3. **Each item** with its category, its words from the page, and a reason a person can disagree with: "Set in capitals, the way an element is introduced." "Anything an actor handles has to be there on the day." 4. **Implied items** (somebody writes, so there is something to write with) are labelled as inferred and offered with a name to change. 5. **Add** and **Not needed** on each. A dismissal is kept, so the same item is not offered again. 6. A neutral count: "Suggestions waiting". Never "missed" or "ignored". There is no **Accept all** for anything that reaches the script. A batch the person asked for (making twelve calendar dates from one sentence) is allowed, and its toast says each item can be changed: "12 dates added. Each can be changed or removed." ### Move the writer's words: the revision mark When a machine proposes words in the work itself, they carry a [revision mark](https://kwark.space/designSystem/components/revision-mark.md): a soft tint, a dotted rule and an asterisk in the right margin, with a [provenance label](https://kwark.space/designSystem/components/provenance-label.md) that names the source, such as "* Suggested · from your outline, Act 2", and the line it came from. Buttons name the result: **Use heading**, **Edit**, **Not needed**. - Accepted: the tint and star go; history keeps where it came from. - Edited: the words are the person's. No mark. - Dismissed: gone, and not offered again. - Undone: one step. The star is the film industry's own mark for a changed line; it prints, it is flat, and it disappears the moment a person makes the words theirs. ### Ask in your own words: the prompt input Where Kwark accepts a sentence (the calendar's quick add, screenplay search), use the [prompt input](https://kwark.space/designSystem/components/prompt-input.md). It works like this: - A label that says what it does ("Add to the calendar", "Search the screenplay") and an example of how to ask, not a chat persona. - Parsed on the device. Nothing is sent anywhere. - A preview of exactly what will be made before anything is made: the date, time, people and scenes read from the sentence, each editable. - One action to make it, named with the result ("Add table read"), and Undo after. It is a form that understands sentences, not a conversation, and it never writes into the screenplay. ### Hand off: Copy for AI The character page's **Copy for AI** is how Kwark meets the AI tools people already use, without becoming one: - **Choose what travels:** presets (Essentials, Full character, Actor preparation, Relationship, Custom selection), with "Include individual relationships & notes" as a separate choice. Only the chosen fields are projected into the prompt; whole records are never serialised. - **Say what is and is not happening:** "Kwark prepares the prompt on your device. You decide where to paste it and what to share with that service. There is no AI chat or automatic sending here." Status: "Ready to copy. Nothing has been sent to an AI service." - **Three steps:** Copy the prompt; Open a new AI chat; Paste, send, choose a mode. - **The prompt protects the work:** it tells the other AI that the character material is reference, not instructions; to use only supplied facts; not to invent history as established; and never to claim that agreement there changes the record in Kwark. Its first reply is only a menu of modes, then it waits. - **Fallbacks in words:** "Your browser could not copy automatically…", **Download JSON** with "JSON download started. Open the file and copy its contents into your AI chat." What the person does in their own AI chat is their choice. Kwark's prompt never asks that AI to score or grade the writing. The AI storyboard pack, when built, follows the same shape for a scene: a PDF, a zip of images and a master prompt; the prompt asks for character and location references first; the person uploads results back onto the panels, marked "Imported image" until edited. No generation on Kwark's servers, which would also break the free-tier budget. ### Multi-step machine actions: plan, activity, stop Nothing in Kwark today runs a multi-step machine task on the work. If one is ever built (for example, proposing a breakdown for a whole act), it must: - **Show the plan first** with the [agent plan](https://kwark.space/designSystem/components/agent-plan.md): the steps, what each reads and what each would change, in a list the person approves. - **Show activity while it runs** with [agent activity](https://kwark.space/designSystem/components/agent-activity.md), step by step, with a **Stop** that works at once and keeps what is done. - **End in a review**, not an apply, with the [AI result review](https://kwark.space/designSystem/components/ai-review.md): every proposed change listed with its source, accepted one by one, with dismissals kept. - **Be one Undo** away, as a single [undo entry](https://kwark.space/designSystem/components/ai-undo-entry.md) in the history named for what it did ("Undo: 14 breakdown items from Act 2"). ## Anatomy | Part | Means | Rule | |---|---|---| | Source heading | Where the material came from | Words, never a sparkle: "The script mentions", "from your outline" | | Reason line | Why this was offered | A plain sentence, never a confidence percentage | | Status line | That nothing has happened yet | "Nothing here counts until you say so." | | Per-item actions | Accept or refuse this one | **Add** / **Not needed**, **Use heading** / **Edit** / **Not needed** | | Revision mark | Proposed words in the work | Tint, dotted rule, margin star, until a person accepts or edits | | Provenance label | The mark's words | "* Suggested · from your outline, Act 2" | | Consent line | What leaves the device and to whom | Before anything is sent; off by default; per project | | Undo entry | The reversal | One step, named for what it undoes | ## Rules - **Never** score, grade, rate, critique, rank, compare or rewrite a person's writing, or show any percentage that rates it (Decision 0002). - **Never** write machine-proposed words or items into the work without a person accepting each one. - **Never** offer Accept all for anything that reaches the script. - **Never** mark machine help with sparkles, glows, gradients, purple, or an "AI" badge. Say the source in words. - **Never** show confidence scores. A guess is labelled a guess. - **Never** complete the writer's sentence as ghost text; Tab belongs to the screenplay. - **Never** send a person's work to an outside service unless they turned it on for that project, knowing what is sent and to whom; and never for a student until guardian consent exists. - **Must** give every suggestion its source, a reason, and a refusal that sticks. - **Must** make every machine action undoable in one step. - **Must** ask with the [AI consent prompt](https://kwark.space/designSystem/components/ai-consent.md) before anything leaves the device, and label every handoff with what is and is not sent: "Nothing has been sent to an AI service." - **Always** run guesses on the device when possible; a cloud call costs the free tier and the person's privacy. - **Always** say plainly what exists today; never claim a model, feature or protection that does not. ## Edge cases - **The page changes after a suggestion.** If the words it came from are gone, the suggestion goes too; it never points at text that no longer exists. - **Two editors.** A suggestion accepted by one person is accepted for the project; a dismissal by one is a dismissal for all, and the history says who. - **Read-only people** see no suggestions; there is nothing they could accept. - **Indian scripts.** Suggestions read the script as written; phonetic conversion never runs on words the writer chose to keep Roman. - **A pasted prompt-like text inside a character note.** The handoff treats it as reference material, never as instructions. - **Offline.** On-device guesses work; anything that would send text out says it cannot run and does nothing else. ## Phone and desktop On desktop, suggestions sit in the panel beside the page they came from, and a revision mark's actions sit under the marked line. On a phone, suggestions are a sheet opened from Menu ("The script mentions"), each item a 44px row with Add and Not needed; the revision label and its actions sit directly under the line, never in a hover. The handoff dialog is a full-screen sheet with the three steps in order. ## Writing - Name the source: "The script mentions", "from your outline", "Imported image". - Say nothing has happened yet: "Nothing here counts until you say so." "Ready to copy. Nothing has been sent to an AI service." - Name refusals plainly: **Not needed**, never "Reject" or "Ignore". - Never "AI-powered", "magic", "smart" as a selling word, or "Let AI…". *Smart phonetic suggestions* names one setting and says what it costs. ## Accessibility - A revision mark's label is linked to the marked text with `aria-describedby`, so a screen reader hears "Suggested, from your outline, Act 2" with the words. - Suggestions are a list; each item's actions include the item in their names ("Add Reel 3", "Reel 3 not needed"). - The tint is never the only signal: the margin star and the label carry the meaning, and both print. - Status lines ("Nothing has been sent…") are visible text, not tooltips. **Do:** Offer **Reel 3** under "The script mentions", with its reason and **Add** or **Not needed**. **Don't:** Fill the breakdown with 40 items and toast "AI found 40 props" with a sparkle. **Do:** "* Suggested · from your outline, Act 2" beside a tinted heading, with **Use heading**, **Edit**, **Not needed**. **Don't:** "Here is a stronger version of Mira's line" with a rewritten speech and a score of 82%. **Do:** Copy for AI: choose what travels, "Nothing has been sent to an AI service.", then paste it in the chat the person picks. **Don't:** A chat sidebar inside the screenplay that edits the script as it talks. ## Demo ```html

INT. EDIT SUITE – NIGHT

* Suggested · from your outline, Act 2

From the beat "Mira finds the splice in the edit suite, night."

What
Table read
When
Next Tuesday · 19:00–21:00
Who
Meera
Scenes
4, 7
Read on this device. Nothing is sent anywhere.
Copy for AI
Kwark prepares the prompt on your device. You decide where to paste it and what to share with that service. There is no AI chat or automatic sending here.
Ready to copy. Nothing has been sent to an AI service.
12 dates added. Each can be changed or removed.
``` ## Related [AI and authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md), [Revision mark](https://kwark.space/designSystem/components/revision-mark.md), [Suggestion panel](https://kwark.space/designSystem/components/suggestion-panel.md), [Provenance label](https://kwark.space/designSystem/components/provenance-label.md), [AI consent prompt](https://kwark.space/designSystem/components/ai-consent.md), [Prompt input](https://kwark.space/designSystem/components/prompt-input.md), [Agent plan](https://kwark.space/designSystem/components/agent-plan.md), [Agent activity](https://kwark.space/designSystem/components/agent-activity.md), [AI result review](https://kwark.space/designSystem/components/ai-review.md), [AI undo history](https://kwark.space/designSystem/components/ai-undo-entry.md), [Toast](https://kwark.space/designSystem/components/toast.md), [Search and filter](https://kwark.space/designSystem/patterns/search-and-filter.md), [Print and export](https://kwark.space/designSystem/patterns/print-and-export.md), [Structure, not teaching](https://kwark.space/designSystem/method/structure-not-teaching.md). ## AI readiness test **Task:** Offer filming locations for the Locations list from the screenplay of Blank Pages. **Give the agent:** This page, AI and authorship, Revision mark, Decisions 0002, 0004, 0005. **Constraint:** On the device; nothing added until the person agrees; no judgement. **A reliable answer:** - Each location offered with the scene heading it came from and a plain reason - Add and Not needed per item, dismissals remembered, no Accept all - A neutral count and "Nothing here counts until you say so." - No sparkles, confidence scores or AI badges - One Undo for each addition - nothing sent off the device --- # Collaboration > 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. Source: https://kwark.space/designSystem/patterns/collaboration ## The problem A writer and her co-writer work on the same script from two cities. A director reads along and leaves notes. An actor opens the scene the night before a table read. They need to know who else is in the project and where, to talk about a specific line without copying it into a chat, and above all to never find that the other person's laptop has replaced their afternoon's work. Collaboration features are also where tools become noisy: avatars of everyone who ever opened the file, cursors flickering across the page, red badges, a feed of activity. Kwark is a calm place to write; the work stays in front. ## Kwark's answer ### Presence: only when someone is here The presence bar (`components/presence/PresenceBar.tsx`) is **empty when nobody else is here**. That is the ordinary case, and it should take up no room at all rather than announcing that you are alone. When others are here it shows up to five initials in each person's colour, then "+{n}". Each mark's tooltip says who and where: "Dev Rao — in the screenplay", "Asha — in characters". The bar's accessible name counts them: "2 other people here". Presence is per project, with the module each person is in, so a director on the Breakdown can see the co-writer is in the screenplay without either being interrupted. ### Cursors: where the hand is, in page terms `PresenceCursors.tsx` draws other people's pointers over a surface: - Positions are fractions of the surface, not pixels, so a cursor lands on the same place on the page for someone with a different window size. - **Only people who can change what they are looking at broadcast a pointer.** A reader's cursor drifting across your script tells you nothing you need, and it is not free on the free tier. - Leaving the surface takes the cursor away rather than stranding it at the edge. - The layer ignores the mouse entirely, so nothing can come between someone and their work. Movement between messages is smoothed by a transition, not by sending more messages. - In the screenplay, a co-writer's caret shows with their name at the insertion point. ### Comments: anchored, quiet, resolvable The comment dock (`components/comments/CommentDock.tsx`): - **New comment** asks you to "Tap what it is about": a line, a card, a shot. The comment is pinned there. - A thread shows **On this screen** or **On another view**, so a note made in the Breakdown about Scene 12 is not lost when you read the script. - Each thread: **Reply** ("Write a reply"), **Resolve**, **Reopen**, **Edit**, **Delete**. Resolved threads move out of the way, not out of existence. - Filters: which comments to show (open or resolved), whose (**Everyone** or a person), **Newest** or **Oldest** first. - Mentions: "@" a person; they see "Someone mentioned you" (or "{n} remarks mention you") with **Show**. - Empty: "Nothing said here yet. Start the conversation." / "No comments here yet." / "Nothing has been resolved here." - On the page, a **comment pin** (a mango tag with the count) marks the line. On a phone, a dot on the floating button means comments are waiting for you (Decision 0016); on the screenplay's Menu, the same dot. ### Two sessions, one script The screenplay is protected by revision stamps (see [Saving and sync](https://kwark.space/designSystem/patterns/saving-and-sync.md)). If the script was changed in another session while you wrote: > **This screenplay was changed in another session.** Your edits are kept on this device and have not overwritten it. Loading the newer version saves yours as a snapshot first. with **Load the newer version** and **Keep mine**. Nothing is lost either way. When the same person opens the editor in a second window, the session lock offers to take over: "Taking over closes editing in the other window and safely transfers the latest text here." The other window becomes read-only with "Close and keep reading". The audit flagged this dialog's Title Case labels ("Active Editing Session", "Resume Editing Here") as words to fix: the pattern is right, the words are not yet. ## Anatomy | Part | Means | Shown | |---|---|---| | Presence marks | Who else has this project open, in their colour | Only when someone else is here | | "+n" | More people than the five shown | When more than five | | Peer cursor | Another editor's pointer, in page terms | Only for people who can edit | | Peer caret with name | Where a co-writer is typing | In the screenplay | | Comment pin with count | Comments on this line or object | On the page | | "On this screen" / "On another view" | Where a thread is anchored | In the dock | | Dot on the floating button or Menu | Comments waiting for you | Phones and the screenplay | | Conflict banner | Two sessions changed the script | Until you choose | ## Rules - **Must** hide presence entirely when nobody else is here. - **Must** broadcast pointers only from people who can edit, and drop them when they leave the surface. - **Must** anchor every comment to what it is about, and show where when it is on another view. - **Must** keep both versions when two sessions change the screenplay; the writer chooses. - **Never** show read receipts, "last seen", typing indicators for readers, or a public activity feed. The audit's chair rejected read receipts. - **Never** pulse, animate or colour-alarm a badge to draw people back. - **Never** let a comment, cursor or presence layer intercept a click on the work. - **Always** use each person's one colour everywhere (presence, cursor, caret), and always with their initials or name, never colour alone. - **Always** count presence and cursor traffic against the free tier: one shared presence room per project, no per-module listeners. ## Edge cases - **Someone joins as a Reader.** They appear in presence (others know who is reading) but do not broadcast a cursor. - **A person is removed while here.** Their marks leave at once; on their side, the named access-ended page. - **Many people at a table read.** Five marks and "+n"; the dock filter **Whose comments to show** narrows to one person. - **Offline.** Comments queue on the device like any change; presence simply shows nobody. - **A comment on text that was later cut.** The thread stays and says it is on another view; it is never silently deleted with the text. - **Indian-script names.** Initials come from the first letter as written; never force Latin initials. ## Phone and desktop On desktop, presence marks sit in the project header at the right; the comment dock is a side panel beside the page. On a phone, presence sits in the Menu sheet's header, the dock is a full-height sheet opened from **Comments** in the floating button, and **New comment** asks you to tap what it is about before you write. Cursors are not drawn on phones; carets are. ## Writing - Presence tooltip: "{Name} — in {module}", with plain module names ("the screenplay", "the outline", "the calendar"). - Dock: **New comment**, "Tap what it is about", "Write a comment", "Write a reply", **Send comment**, **Send reply**, **Resolve**, **Reopen**. - Mentions: "Someone mentioned you", "{n} remarks mention you", **Show**. ## Accessibility - Presence is a group with a counted label; each mark has the person's name and place as its accessible name, not only a tooltip. - Peer cursors are `aria-hidden`; they are visual help, and announcing every move would be noise. - Comment pins are buttons named with the count: "2 comments on this line". - The dock is a dialog on phones and a complementary region on desktop; new replies are announced politely. **Do:** No presence bar at all when you are alone; "Dev Rao — in the screenplay" when Dev arrives. **Don't:** "You're the only one here" with an empty avatar ring, all day. **Do:** A conflict banner with **Load the newer version** and **Keep mine**, both safe. **Don't:** The last device to save wins, and the co-writer's afternoon is gone. ## Demo ```html
Comments
DRDev RaoOn this screen

Should the reel be on the desk already when Mira comes in?

AKAsha KumarOn another view

Breakdown: the reel needs a prop number.

``` ## Related [Avatar](https://kwark.space/designSystem/components/avatar.md), [Presence cursor](https://kwark.space/designSystem/components/presence-cursor.md), [Comment pin](https://kwark.space/designSystem/components/comment-pin.md), [Sharing and roles](https://kwark.space/designSystem/patterns/sharing-and-roles.md), [Saving and sync](https://kwark.space/designSystem/patterns/saving-and-sync.md), [Notifications](https://kwark.space/designSystem/patterns/notifications.md). ## AI readiness test **Task:** Add live presence to the Schedule's stripboard. **Give the agent:** This page, Review and quality (free tier), components/presence/*. **Constraint:** Reuse the project's presence room. **A reliable answer:** - Reuses the shared presence room with module "schedule", no new listener - Shows marks only when others are here - Broadcasts pointers only from editors, as fractions of the board - A strip being dragged by someone else shows their colour and name, and two moves to the same strip keep both until one is chosen - No read receipts or activity feed --- # Destructive actions > 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. Source: https://kwark.space/designSystem/patterns/destructive-actions ## The problem A writer tidying her library at midnight deletes the wrong story. Or a producer removes an actor from the project five minutes before the actor needs tomorrow's call sheet. Or an owner taps "Remove cover" and the poster she made goes black. Two opposite failures sit here. A tool that asks "Are you sure?" before everything trains people to click Yes without reading, so the one dialog that matters is ignored. A tool that asks before nothing loses work. Kwark's principle 12 is that the work is never at risk; principle 9 is that Kwark is quiet. Destructive actions have to serve both. ## Kwark's answer ### Undo first, confirm rarely Choose the gentlest form that keeps the work safe: | The action | Form | Example | |---|---|---| | Reversible, affects only you | Do it, then a toast with **Undo** | Remove cover: "Cover removed." with Undo, no dialog (Decision 0017) | | Reversible for 30 days | Move to trash, with a toast | **Move to trash**, "Moved to trash", restore from the trash drawer | | Changes what other people can see or do | A confirm that names who and what | "Remove Dev?" / "They lose access straight away and "Blank Pages" leaves their library. Their comments stay. You can add them again later." | | Cannot be undone | A confirm that names exactly what goes, says "This cannot be undone", and uses the action as the button | "Delete this story for good?" **Delete for good** | | Replaces the writer's own work | A confirm with a way to keep theirs | Pitch: "Replace this treatment with the outline's beats?" **Replace** / **Keep mine** | ### The trash Deleting a story moves it to the trash. The trash says: "Kept here for 30 days, then deleted for good. Restore brings a story back." An empty trash says "Nothing here" and "Stories you delete stay here for 30 days." Scenes removed from a script can be restored from Trash for 30 days too. From the trash, **Delete for good** and **Empty trash** are the only irreversible actions on a story, and both confirm: - "Delete this story for good?" / ""{name}" and everything in it will be deleted from this device and the cloud. This cannot be undone." **Delete for good** - "Empty the trash?" / "{n} stories and everything in them will be deleted for good, from this device and the cloud. This cannot be undone." **Empty trash** If it does not work, nothing is lost and the words say so: "This project could not be deleted just now. It is still in the trash." "The trash could not be emptied just now. Nothing was lost." A story shared with you is not yours to delete; hiding it says "Shared with you and not deleted. Whoever shared it still has it." The audit found the old empty-trash deleted the cloud project at once, in one large batch that could fail halfway. The 30-day trash and smaller batches came from that finding. ### Removing people Removing someone changes another person's work, so it confirms, and the message says what they keep: - Joined: "Remove {name}?" / "They lose access straight away and "{title}" leaves their library. Their comments stay. You can add them again later." - Invited, not joined: "Cancel the invitation to {email}?" / "Their address comes off the list, and the project will not appear when they sign in." - Cast and crew: "Take them off this project?" / "They stay in your directory and on other projects. Only this film's roster changes." **Take them off** - Leaving a project you were invited to: **Leave project**. A person who was removed sees a named "access ended" page, never "the project has been deleted" (Decision 0042). ## Anatomy of a confirm | Part | Rule | |---|---| | Title | A question that names the thing: "Delete this story for good?", "Remove Dev?" | | Message | Exactly what goes, from where, and what stays. "This cannot be undone." only when true. | | Safe button | Quiet, first, focused by default: **Keep** or **Cancel** | | Destructive button | The action as its label, in danger style: **Delete for good**, **Empty trash**, **Remove access** | | No icon theatre | No pulsing shield, no glow, no coloured stripe. The legacy `ConfirmDialog` has these; the system does not. | ## Rules - **Must** offer Undo for any reversible destructive action, in a toast that stays 8 seconds and pauses on hover or focus. - **Must** move stories to a trash that keeps them 30 days, and say so where the trash is. - **Must** confirm before anything that cannot be undone, and before anything that changes what other people can see or do. - **Must** name the thing, the scope ("from this device and the cloud") and what survives ("Their comments stay"). - **Must** label the destructive button with the action. Never "Yes", "OK", or the legacy default "Yes, do it". - **Never** confirm a reversible action. A dialog before Remove cover is noise. - **Never** delete in one unbounded batch; work in batches that can resume, and say what happened if one stops. - **Never** use a confirm to scare: no red header bars, pulsing icons, capitals or exclamation marks. - **Always** put the destructive item last in a menu, after a separator, in danger text. - **Always** focus the safe choice first in a confirm, so Enter does not destroy. ## Edge cases - **A shared project in your library.** You can hide it or leave it; you cannot delete it. The words say the owner still has it. - **Undo after navigating away.** The toast's Undo still works while the toast is visible; after that, restore from the trash. - **Deleting a scene the schedule uses.** The strip leaves the board and the call sheet's draft changes; issued revisions are frozen and do not change (Decision 0020). - **Offline.** A trash move happens on the device at once and syncs later. Delete for good waits for the cloud and says it will. - **Bulk.** "Empty trash" counts what will go in the message. Twenty stories are named as "20 stories", never hidden behind "items". - **Replacing work with generated structure.** Always keep the writer's version reachable (**Keep mine**, or a restore point taken first). ## Phone and desktop On a phone, destructive actions live in a row's ⋯ sheet, last, in danger text; the confirm is a bottom sheet with the safe action on the left and the destructive one on the right, both 44px. Undo toasts sit above the floating button. On desktop, the confirm is a small dialog (no wider than 480px) and Escape is the same as Keep. ## Writing - Name the action the same way through the flow: Move to trash, then "Moved to trash"; Delete for good, then "Story deleted for good"; Restore, then "Story restored" and "It is back in your library". - "This cannot be undone." is a plain sentence, last, and only when it is true. - Say what stays: comments, the directory, other projects, the copy elsewhere. ## Accessibility - A confirm is `role="alertdialog"` with its message linked by `aria-describedby`; focus starts on the safe button and returns to the trigger. - The Undo toast is in a polite live region and its button is reachable by keyboard before it dismisses; the timer pauses on focus. - Danger is shown in words and in the button label, not by colour alone. **Do:** "Cover removed." with **Undo**, and nothing else. **Don't:** "Are you sure you want to remove the cover?" with **Yes** and **No**. **Do:** "Delete this story for good?" ""Blank Pages" and everything in it will be deleted from this device and the cloud. This cannot be undone." **Keep** / **Delete for good** **Don't:** "Confirm action" "This action is irreversible." **Cancel** / **Yes, do it**, under a pulsing red shield. ## Demo ```html
Moved to trash.

Remove Dev?

They lose access straight away and "Blank Pages" leaves their library. Their comments stay. You can add them again later.

``` ## Related [Dialog](https://kwark.space/designSystem/components/dialog.md), [Toast](https://kwark.space/designSystem/components/toast.md), [Menu](https://kwark.space/designSystem/components/menu.md), [Errors](https://kwark.space/designSystem/patterns/errors.md), [Sharing and roles](https://kwark.space/designSystem/patterns/sharing-and-roles.md), [Saving and sync](https://kwark.space/designSystem/patterns/saving-and-sync.md). ## AI readiness test **Task:** Add "Delete shot" to Shots & Boards. **Give the agent:** This page, Decision 0017, Decision 0020, Toast. **Constraint:** Prefer the gentlest safe form. **A reliable answer:** - Deletes at once with "Shot deleted." and Undo, no dialog, because it is reversible - The item is last in the shot's menu after a separator, in danger text - Boards drawn for the shot are kept with the undo - Issued call sheet revisions are not changed - No "Are you sure?" --- # Empty states > 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. Source: https://kwark.space/designSystem/patterns/empty-states ## The problem A producer opens Kwark on Monday to make the first call sheet for a five-day shoot. The Call sheets screen is empty. If it shows a cartoon clapperboard and "Nothing to see here", she learns nothing: she does not know whether call sheets are made here, whether she has to set something up first, or whether something is broken. Empty screens are where people decide whether a tool understands their work. In Kwark they are also where the [one-script promise](https://kwark.space/designSystem/method/competitors-are-the-floor.md) is either visible or not: a call sheet is empty because the schedule is, and the schedule is empty because the screenplay has no scenes yet. The empty state is the place to say so. ## Kwark's answer An empty state answers three questions, in this order: 1. **What goes here?** The heading names the thing: "No call sheets yet", "No cast yet", "No beats yet". 2. **Where does it come from?** One or two sentences that say how this fills, especially when it fills from somewhere else: "The schedule is built from the screenplay's scene headings." 3. **What can I do now?** One action, named with a verb and the object. If the thing fills from elsewhere, the action takes them there. It is calm and factual. It does not celebrate, apologise, joke or teach. Decision 0004 keeps coaching out of it: the empty outline card once asked "What does an ordinary day look like before anything changes?"; since 4 November it says "Add words…". ### Five kinds of empty | Kind | What the person needs | Example | |---|---|---| | Nothing made yet | What goes here and the way to start | "No locations yet. Locations you add here appear on every call sheet that uses them." **Add location** | | Fills from elsewhere | Where it comes from, and a route there | "No scenes to schedule yet. The schedule is built from the screenplay's scene headings. Write or import the script, and every scene arrives here as a strip." | | Nothing matches | That the search or filter is the cause, and how to undo it | "No stories found. Try a different title, format, or status." **Clear filters** | | Nothing yet, by design | That it is quiet on purpose | "Nothing has been resolved here." (Comments, Resolved filter) | | Cannot be seen | That it is not empty, it is not shared | "{Owner} hasn't shared {module} with you." See [Sharing and roles](https://kwark.space/designSystem/patterns/sharing-and-roles.md) | Never show the "nothing made" message when the real state is loading, offline, not downloaded or no access. Those have their own patterns and words: [Loading](https://kwark.space/designSystem/patterns/loading.md), [Saving and sync](https://kwark.space/designSystem/patterns/saving-and-sync.md). ## Anatomy | Part | Rule | |---|---| | Heading | "No {things} yet", or the plain state. Sentence case. Title size. | | Line | One or two sentences: where this fills from, what it becomes. Quiet text. | | Action | At most one primary button. A second, quiet link only for a real alternative (import). | | Frame | `kw-empty`: dashed strong line, card radius, left-aligned, no icon required. | The dashed edge means "a place for something". It is the only decoration an empty state gets. The founder rejected decorative illustrations in the design system; the app's Home does draw a small story frame on an empty library, and that is the exception, not a template. ## Real copy from the app - **Home, no stories:** "Every story starts somewhere." / "Make a little room for your next idea." **Start a story** - **Home, filters on:** "No stories found" / "Try a different title, format, or status." **Clear filters** - **Call sheets:** "No call sheets yet" / "A call sheet is made for each shooting day, and the days are built from the screenplay's scenes. Write or import the script, then schedule its days." - **Schedule:** "No scenes to schedule yet" / "The schedule is built from the screenplay's scene headings. Write or import the script, and every scene arrives here as a strip." - **Colour and texture:** "No characters yet" / "A character gets a colour once there is a character. Write one in the character module and they arrive here…" - **Continuity photos:** "No continuity photos yet. On the day, take one of each character before the first take of every scene." - **Outline timeline:** "No beats yet. Open Writing to begin the story." - **Comments:** "Nothing said here yet. Start the conversation." / "No comments here yet." - **Trash:** "Nothing here" / "Stories you delete stay here for 30 days." - **Script search:** "Nothing in the script matches that." - **Outline card:** "Add words…" The continuity line is the edge of what is allowed: it says when the artefact is made on set, which is how the sheet fills, not how to do the job well. A line that explained why continuity matters would be teaching. ## Rules - **Must** name what goes here in the heading, with the noun the person uses. - **Must** say where the content comes from when it fills from another module, and give a route there. - **Must** distinguish empty from loading, offline, not downloaded, filtered and no access. - **Must** give a filtered-empty list a **Clear filters** action, and keep the filters visible. - **Never** use jokes, mascots, illustrations made for the empty state, or exclamation marks. - **Never** coach the craft: no questions to the writer, no "a great logline should…". - **Never** guilt or count: no "You haven't written in 6 days", no streak, no progress ring. - **Never** put more than one primary action in an empty state. - **Always** keep the page's header, tools and title in place, so the empty state reads as this screen with nothing in it, not a different screen. - **Always** let typing replace the empty state at once: an empty card that is clicked becomes the field. ## Edge cases - **Read-only person, empty module.** No action button; the line says what will appear and who adds it: "Scenes appear here when Mira writes them." - **Guest with no account.** Say where the work is kept: "No account needed. Your story is kept on this device until you sign in." - **Empty because a feature is switched off.** Show the switch, not an empty panel (the beat map off shows only **Map the outline onto the script**). - **Partially empty.** A call sheet with scenes but no hospital is not empty; it is incomplete. Use an inline notice on the missing part ("Location to be confirmed. Add it before issuing the call sheet."). - **Very first visit.** Home's empty library is the [first frame](https://kwark.space/designSystem/patterns/first-run.md), not a generic empty state. ## Phone and desktop On a phone the empty state starts by about y = 200 under the one-line header, fills the column width with 16px gutters, and its button is full height (44px). On desktop it sits where the content would, left-aligned, at the content's measure, never centred in a huge void. The floating button's slot at the foot is kept clear on phones. ## Accessibility - The heading is a real heading at the right level for the page, so screen-reader users hear the section is empty. - When a filter empties a list, announce the result in a polite live region: "No stories found." - The action is a native button or link with its full name ("Add location", not "Add"). - Dashed borders are decoration; the meaning is in the words. **Do:** "No scenes to schedule yet. The schedule is built from the screenplay's scene headings." **Open the screenplay** **Don't:** A clapperboard drawing and "Lights, camera… nothing yet" with **Get started**. **Do:** An empty outline card that says "Add words…". **Don't:** An empty outline card that asks "What does your hero want more than anything?" **Do:** "No stories found. Try a different title, format, or status." **Clear filters**, with the filter row still showing what is on. **Don't:** The welcome empty state for new users, shown because the search returned nothing. ## Demo ```html

No locations yet

Locations you add here appear on every call sheet that uses them.

No stories found

Try a different title, format, or status.

No scenes to schedule yet

The schedule is built from the screenplay's scene headings. Write or import the script, and every scene arrives here as a strip.

Open the screenplay
``` ## Related [Empty state](https://kwark.space/designSystem/components/empty-state.md), [Loading](https://kwark.space/designSystem/patterns/loading.md), [First run](https://kwark.space/designSystem/patterns/first-run.md), [Search and filter](https://kwark.space/designSystem/patterns/search-and-filter.md), [Structure, not teaching](https://kwark.space/designSystem/method/structure-not-teaching.md). ## AI readiness test **Task:** Write the empty state for the Budget when the schedule has no days. **Give the agent:** This page, Decision 0004, Decision 0022 (budget follows cast and locations). **Constraint:** One action; no coaching. **A reliable answer:** - Heading names the thing ("No budget lines yet" or similar) - The line says the budget fills from cast, locations and scheduled days - The action routes to the schedule or the cast list - Distinct copy for read-only people with no button - No illustration, joke or exclamation mark --- # Errors > 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. Source: https://kwark.space/designSystem/patterns/errors ## The problem It is 1 a.m. A writer has just finished the scene she has been avoiding for a week. The screen says "Cloud sync failed". She does not know what the cloud is doing, whether the scene exists, or whether to close the laptop. The word "failed" lands on her, not on the network. Before October 2026 this was real. Raw Firebase text such as "auth/network-request-failed", "Cloud sync failed" and "An error occurred" reached writers, and a refused write was dropped without a word. The 17 October audit ranked plain sync words and friendly errors in its top ten for the producer meeting. An error in a writing tool is not a technical event. It is a moment when the writer fears for their work. The message has one job: answer that fear truthfully, then help. ## Kwark's answer Decision 0013, a calm voice for sync and errors: **tell the state first. Errors say what happened, that the work is safe if that is true, and what to do. Never "failed".** Every error a person might see goes through one function, `friendlyError()` in `utils/friendlyError.ts`. It maps known codes to a calm sentence, lets Kwark's own sentences pass through, and replaces any library text (anything mentioning Firebase, a stack frame, `TypeError`, `undefined`) with the fallback: "Something went wrong. Your work is safe; please try again." ### The order of a Kwark error sentence 1. **The state of the work**, when it is at stake: "Your work is safe on this device." "Nothing was changed in your script." "It is still in the trash." 2. **What happened**, in the person's terms: "We could not reach the internet." "The sign-in window was closed." 3. **What to do**, if anything: "Try again when you are back online." "Ask the project owner if you need it." Sometimes the state goes first, sometimes what happened does; both must be there when the work is involved. Never say the work is safe when Kwark does not know it is. ### Choosing where the error appears | Situation | Where | Example | |---|---|---| | One field cannot be accepted | Under the field, linked to it | "Choose a date after today, or choose No end date." | | An action did not complete, nothing lost | A toast with the reason and, if useful, the retry | "That change was not saved. Try again." | | The page cannot do its job until something changes | A banner under the header that stays until resolved | "This screenplay has not downloaded to this device. Nothing will be saved until it does." | | The person must choose between two outcomes | A banner with both choices | "This screenplay was changed in another session." with **Load the newer version** and **Keep mine** | | Access is missing | The page itself, with who to ask | "{Owner} hasn't shared {module} with you." | | A whole screen crashed | The error boundary, with a way back to the library | A plain sentence and a route home, never a stack trace | ## Anatomy | Part | Means | Rule | |---|---|---| | Sentence | What happened and the state of the work | One or two short sentences, no code | | Action | The one thing that helps | A verb and an object: **Try again**, **Retry saving**, **Open project** | | Tone | How much this blocks | Warn (amber) when the work is safe but waiting; danger only when work is blocked or would be lost; always with words | | Persistence | How long it stays | Toasts for things that are over; banners for things that are not | ## Real copy from the app These are the sentences `friendlyError()` returns today. Use them; do not write new variants of the same situation. | Code | Sentence | |---|---| | Wrong email or password | That email and password do not match. Please check them and try again. | | Bad email | That email address does not look right. Please check it and try again. | | Email in use | This email already has an account. Try signing in instead. | | Too many tries | Too many tries just now. Wait a few minutes and try again. Your work is safe. | | No network | We could not reach the internet. Your work is safe on this device; try again when you are back online. | | Pop-up closed | The sign-in window was closed. Nothing changed; you can try again. | | Pop-up blocked | Your browser blocked the sign-in window. Allow pop-ups for this site and try again. | | Link expired | That link has expired. Ask for a new one and try again. | | Permission denied | You do not have access to this. Your work is safe; ask the project owner if you need it. | | Cloud unavailable | We could not reach the cloud just now. Your work is safe on this device and will go up when we can. | | Storage full | There is no room left to store this. Your work is safe; try a smaller file. | | Cloud busy | The cloud is busy right now. Your work is safe; try again in a little while. | | Signed out | Please sign in again. Your work is safe on this device. | And from the screens: - "Could not save. Your words are kept on this device." - "That copy could not be made. Nothing was changed in your script. Try again, or use a different format." - "The trash could not be emptied just now. Nothing was lost." - "This project could not be restored. It is still in the trash." - "That request was not answered. Open the project and try from Share." - "Your browser blocked copying. Select the text and copy it yourself." - "The download could not start. You can copy or select the prompt instead." A character edit that cannot be stored stays open and offers **Retry saving**, and the on-screen Back waits for the local save (Decision 0013 history, 4 November 2026). ## Rules - **Must** route every error a person can see through `friendlyError()` or a sentence written for that screen. - **Must** say the state of the work whenever the work could be at stake, and only when it is true. - **Must** keep everything the person typed when validation fails or a retry is needed. - **Must** say what to do next, or say that nothing is needed ("Nothing changed; you can try again"). - **Never** use "failed", "error occurred", "invalid", "denied" or "fatal" in a message a writer reads. The audit also flagged "Access Denied" and "Active Editing Session" as words to replace. - **Never** show raw Firebase, browser or stack text, even in a tooltip. - **Never** apologise at length, blame the person, or use an exclamation mark. - **Never** use red for something that does not block or destroy work. Offline is amber, with words. - **Always** put the reason for a disabled control on the page, not only in a tooltip (Decision 0020 review). - **Always** name a quota for what it is. A project-wide daily ceiling is not a fault in the person's change, and saying so saves them looking for a problem in their own work. ## Edge cases - **Refused because view-only.** The edit stays on the device and is not published; nobody is told their work failed to save when it was never theirs to save. The page itself shows they are reading. - **Private research refused by the server.** It is kept in the queue and retried, not dropped, so it cannot later be mistaken for something deleted elsewhere. - **The same error twice in a minute.** Show it once; update the sentence if the state changes. - **An error behind a dialog.** The dialog stays open with the error inside it, next to the action that caused it. - **Unknown error.** The fallback sentence, and the detail goes to the console for whoever is debugging, never to the screen. ## Phone and desktop The same words on every device. On a phone a banner is one line of what went wrong and how to fix it, with its action wrapping below; long detail moves into the account panel. Toasts sit above the floating button, never under it. A field error sits directly under its field so the on-screen keyboard does not hide it. ## Accessibility - An error toast uses `role="alert"`; a status that does not need interrupting uses `role="status"`. - A field error is linked with `aria-describedby`, and the field has `aria-invalid="true"`. Focus moves to the first invalid field on submit. - The tone is never the only signal: every error has its sentence, and icons are hidden from screen readers when the sentence says the same. - Do not auto-dismiss an error that asks for action. Toasts with an action stay 8 seconds and pause on hover or focus; banners stay until resolved. **Do:** "We could not reach the internet. Your work is safe on this device; try again when you are back online." **Don't:** "auth/network-request-failed" or "Cloud sync failed". **Do:** "This project could not be restored. It is still in the trash." with **Try again**. **Don't:** "Restore failed. Please contact support." in red with a warning triangle. **Do:** Keep the email the person typed, outline the field, and say "That email address does not look right. Please check it and try again." **Don't:** Clear the form and show "Invalid input" at the top of the page. ## Demo ```html
This screenplay has not downloaded to this device. Nothing will be saved until it does, so the copy elsewhere stays exactly as it is.
Mira hasn't shared Characters with you.Ask Mira if you need it.
``` ## Related [Saving and sync](https://kwark.space/designSystem/patterns/saving-and-sync.md), [Forms](https://kwark.space/designSystem/patterns/forms.md), [Toast](https://kwark.space/designSystem/components/toast.md), [Banner](https://kwark.space/designSystem/components/banner.md), [Text input](https://kwark.space/designSystem/components/text-input.md), [UX writing](https://kwark.space/designSystem/foundations/ux-writing.md). ## AI readiness test **Task:** The budget's CSV download throws a quota error from the cloud. Write what the person sees. **Give the agent:** This page, utils/friendlyError.ts, Saving and sync. **Constraint:** Use an existing sentence if one fits. **A reliable answer:** - Uses friendlyError's "The cloud is busy right now. Your work is safe - try again in a little while." or a quota sentence that says it is a daily ceiling, not their fault - No raw code or "failed" - A toast, because the budget itself is unharmed - Offers Try again and keeps the budget open --- # First run > 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. Source: https://kwark.space/designSystem/patterns/first-run ## The problem A student who heard about Kwark from a friend opens kwark.space on her phone between classes. Until November 2026 she met a four-slide introduction: a welcome, a philosophy, the story of the name. The button to start was on the last slide. In the first ten seconds nothing said what Kwark does. Then the worse moments. Someone with no account imported a film, opened it, reloaded, and met the sign-in page; choosing **Continue as Guest** dropped them on Home, not on their page. For a first-time writer that reads as "my work is gone". The project page ran a stopwatch, "Session time", at a person who had only opened their film. And an earlier sign-in reloaded the whole page, after which a dialog appeared. The first minutes decide whether a nervous writer ever writes here. The mission says the way to begin must be obvious and one step away. ## Kwark's answer ### One frame, not a slideshow (Decision 0035) On an empty Home, one frame (`pages/Project/components/FirstFrame.tsx`): - **One sentence:** "Write your film. The rest follows from the page." The last noun cycles through what follows: the breakdown, the shot list, the schedule, the call sheet. - **One line under it:** "The script you write here becomes its breakdown, shot list, schedule and call sheet. Nothing is typed twice." - **The journey in five steps**, each showing a real piece of the sample film and claiming only what the app does today: - Script: "EXT. RAO FARM, VIDARBHA – DAWN" - Breakdown: "Props, cast & places tagged on the page" - Shots: "Scene 1 setups · Establishing at Rao Farm" - Schedule: "12 shooting days, laid out by the hour" - Call sheet: "Day 1 call sheet, issued as Rev 1" - **One button:** **Start a new story**, and the line "No account needed. Your story is kept on this device until you sign in." - Quiet secondary routes: **Open the sample film**, **Import a shared project**. The philosophy and the story of the name stay on the About page (`/info`). The founder chose this layout ("the path of a film") from three mock-ups; the others (the sample film as the front door, and a blank page with the cursor waiting) are recorded with why they lost. The words are the mock-up's; the founder chose the idea, not yet every word. **Agreed, not built (part 2):** each step opens a pop-up holding the real screen, loaded with the sample film, read-only. The sample ships inside the app (no account, no network), is never listed among the visitor's projects, never synced and never adopted on sign-in. When the visitor starts to change something, Kwark asks them to create their own project. ### No account to begin A visitor starts as a guest. Importing a film without an account makes them a guest too (Decision 0034). Guest work lives on the device and is adopted into the account the first time they sign in. Home marks a guest's story **Only on this device**. ### Sign-in opens in place and returns you (Decisions 0010, 0034) - Sign-in navigates inside the app; it never reloads the page, and keeps a marker so guest work is adopted (Decision 0010). - After sign-in or **Continue as Guest**, the app returns to the page that asked, if it is a page of this app (`returnPath` in `utils/signIn.ts`). ### Nothing counts the newcomer - The session stopwatch and its code are gone from the project page (Decision 0034). - There is no automatic tour offer (removed in Decision 0015). **Take the tour** stays in Help for anyone who wants it. - No streaks, goals or "complete your profile" (Decisions 0001, 0008). - "Where you left off" uses the names on the cards (Shots & Boards, Director's Book, Look Book…), never internal names like "Creative lock". ### A returning writer is a different person The founder's words for the returning writer, tired after a ten-hour shift: they should see something and say "yes, I need to write today", and on closing be "content with the work they have done, and excited for the next day". That is a separate decision from the first frame. Today, a returning writer's tap on a story opens Project home, or Where I left off if they chose it (Decision 0018), and **Continue writing** goes straight to where work stopped. ## Anatomy | Part | Means | |---|---| | Headline | What Kwark is, in one sentence | | Line | The promise: one script, nothing typed twice | | Five steps, in order | What one script becomes; screenplay type marks a line of script | | One filled button | The one way to begin | | Small line | No account, and where the work is kept | | Secondary links | The sample film; importing a shared project | ## Rules - **Must** show what Kwark does and the one way to begin in the first frame, on a 375px phone, without scrolling. - **Must** let a visitor start without an account, and say where the work is kept. - **Must** return a person to the page that asked after sign-in or Continue as Guest. - **Must** claim only what the app does today on the first frame. - **Never** show a slideshow, a splash screen, a philosophy or the story of the name before the way to begin. - **Never** start a tour automatically, or time, count or score the first session. - **Never** reload the page on sign-in. - **Never** list the sample film among the visitor's own projects or let it sync. - **Always** keep one primary button on the first frame. - **Always** use real pieces of the sample film, not generic illustrations. ## Edge cases - **A visitor arrives by a shared link.** They see who invited them, as what, before signing in; a link to someone else's project still asks who they are. - **A guest clears their browser.** Guest work is on the device; the first frame's line says so up front, and the account panel offers **Backup**. - **The visitor is 13 to 17.** Kwark serves students from 13. Age and consent steps belong in sign-up, written plainly ("Please complete the 13+ eligibility check and acknowledgements first."), never as a wall before the first frame. - **Shared via WhatsApp or LinkedIn.** The app page carries the same description and picture as `/info`, so a link preview says what Kwark is (Decision 0034). - **An empty Home that is not a first visit** (all stories deleted). Show the ordinary empty library ("Every story starts somewhere."), not the first frame's promise again. ## Phone and desktop The first frame is one screen at 375 wide: the headline breaks after "The {word}", the five steps stack as compact rows, the button is 44px and full width, nothing is under 12px. On desktop the five steps sit in one row and the headline is display size; hovering a step highlights it and pauses the cycling word. The Home toolbar around the frame (search, filters, import) is still shown for a visitor with no projects today; that is an open item, not the pattern. ## Writing - "Write your film. The rest follows from the page." - "The script you write here becomes its breakdown, shot list, schedule and call sheet. Nothing is typed twice." - **Start a new story** · **Open the sample film** · **Import a shared project** - "No account needed. Your story is kept on this device until you sign in." - Shared stories: "When a director, producer, or co-writer invites you to a project, their production workspace arrives here automatically under their banner." ## Accessibility - The frame is a section labelled by its headline. The cycling word is in the heading's text once, not announced on every change; it stops under reduced motion. - The five steps are a list in reading order; each is a link only when part 2 makes it open something. - The primary button is the first focus stop after the heading. **Do:** "Write your film. The rest follows from the page." and **Start a new story** in the first frame. **Don't:** Four slides about the founder's philosophy and the name, with Start on the last. **Do:** After **Continue as Guest**, the visitor lands back on the film they imported. **Don't:** After **Continue as Guest**, the visitor lands on an empty Home and thinks their film is gone. ## Demo ```html
Write your film.
The shot list follows from the page.
The script you write here becomes its breakdown, shot list, schedule and call sheet. Nothing is typed twice.
  1. ScriptEXT. RAO FARM – DAWN
  2. BreakdownProps, cast & places
  3. ShotsScene 1 setups
  4. Schedule12 shooting days
  5. Call sheetDay 1, Rev 1
No account needed. Your story is kept on this device until you sign in. Open the sample film
``` ## Related [Onboarding without teaching](https://kwark.space/designSystem/patterns/onboarding-without-teaching.md), [Empty states](https://kwark.space/designSystem/patterns/empty-states.md), [Navigation](https://kwark.space/designSystem/patterns/navigation.md), [Button](https://kwark.space/designSystem/components/button.md), [Saving and sync](https://kwark.space/designSystem/patterns/saving-and-sync.md). ## AI readiness test **Task:** Build part 2 of the first frame: each step opens the sample film's real screen. **Give the agent:** This page, Decision 0035, Decision 0034, Sharing and roles. **Constraint:** No account and no network needed to look. **A reliable answer:** - Opens the real module in look-only mode from a sample shipped in the app - Never lists, syncs or adopts the sample - Starting to edit asks to create their own project and creates one as Start a new story does - Keeps one primary button and works at 375 wide - Claims only what the screens do today --- # 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
Make room for a story Start with an idea, a title, or nothing at all. Everything here can wait.
Writing format
You can change these anytime.
``` ## 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 --- # Loading > 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. Source: https://kwark.space/designSystem/patterns/loading ## The problem A 1st AD opens the Breakdown on a phone in a basement location with one bar of signal. For several seconds there is nothing. If the screen is blank she wonders whether the scenes are gone; if it shows an empty state ("No scenes yet") she believes it, and may start re-entering them; if it shows a spinner that never resolves she cannot tell slow from broken. There is a worse failure, and it happened. In September 2026 a phone opened a light project card that had not yet loaded the screenplay, and saved its placeholder over ten real pages. A loading state is not only a matter of patience; a screen that does not know it is loading can destroy work. ## Kwark's answer ### Know the difference between loading and empty Every screen that fills from the cloud tracks whether it has its data yet. Until it does, it shows the loading state; only when the data has arrived and there is none does it show the empty state. The screenplay makes this explicit with a lifecycle: **Loading…**, then **Up to date**, **Edited**, **Saving…**, **Saved**, or **Not downloaded**. ### Never save from a screen that has not loaded An unhydrated project (no screenplay on the device and the cloud unreachable) opens **read-only and never saves**. The banner says: "This screenplay has not downloaded to this device. Nothing will be saved until it does, so the copy elsewhere stays exactly as it is." with **Try again**. This is the rule that closed the placeholder-overwrite bug. ### Say what is opening, in the module's own words Production screens say what they are waiting for, in a quiet line where the content will appear: - "Opening the script…" (Breakdown, Shots & Boards) - "Opening the desk…" (department desks, Camera & Light) - "Opening the board…" (Research boards, character notes) - "Loading projects" (Home's accessible label while the library arrives) The line names the thing, not the machinery. It does not say "Fetching data" or "Please wait". ### Keep the frame steady The header, the breadcrumb or one-line phone header, and the module's tools render at once. Only the content area waits. When content arrives it fills the space the loading state held, so nothing jumps. Where the shape is known and the wait is likely to be noticeable (a list of story cards, a page of script), a skeleton in that shape holds the place; it is never used for less than about half a second of waiting, or it flashes. ### Long work shows progress Work that takes seconds and has a measurable end shows a progress toast that stays until done: - Import: "Importing {project}: {n}%", then "Saved locally · cloud sync queued" or "Import needs attention". - Export: the export dialog says **Exporting…** on its button and "Ready to export" before you start. - A spinner with words, such as "Preparing print preview", for work with no measurable end. ### Settle, then step back A status that is good news is worth a glance, not a permanent tenant. **Up to date** and **Saved** show, then step back after about 2.6 seconds. Anything the person must act on stays. ### Load less Heavy parts load only when used: the three-dimensional storyboard figures are a separate chunk loaded when the Boards view opens, and the 2D fallback draws meanwhile. Every listener is shared across modules, and lists are not re-read to redraw (see [Review and quality](https://kwark.space/designSystem/method/review-and-quality.md)). The fastest loading state is the one that is never shown. ## Anatomy | Part | Use | Never | |---|---|---| | Quiet line ("Opening the script…") | Most module content, short waits | As a permanent footer | | Skeleton (`kw-skeleton`) | Known shapes, waits over about half a second | Under half a second; for things of unknown shape | | Spinner with words (`kw-spinner`) | Work with no measurable end, inside a button or a small area | Alone, without words; full screen | | Progress toast (`kw-toast--progress`) | Import, export, uploads: anything with a count or a percentage | For ordinary saving | | Busy button (`aria-busy`) | The action the person just pressed | Changing its label to something unrelated | | Not downloaded banner | The screen cannot load and will not save | As an error toast | ## Rules - **Must** track loaded versus empty separately, and never show an empty state before the data has arrived. - **Must** open a project read-only, and never save, when its screenplay has not reached the device. - **Must** render the header and tools at once; only the content waits. - **Must** name what is opening in the module's words. - **Must** show progress, with a number, for imports, exports and uploads. - **Never** show a full-screen spinner, a splash screen or an idle curtain. The idle curtain that blanked the screen after 60 seconds was removed (Decision 0012). - **Never** show a spinner without words. - **Never** animate a skeleton under `prefers-reduced-motion`; it stays still. - **Always** let "Saved" and "Up to date" step back on their own. - **Always** keep the person's place when content arrives: scroll position, selection, focus. ## Edge cases - **Slow but working.** After about ten seconds, the quiet line may add the state: "Opening the script… This is taking longer than usual. Your work is safe." - **Cloud unreachable, data on the device.** Open from the device at once; the sync word says "Saved on this device". - **Cloud unreachable, nothing on the device.** The Not downloaded banner, read-only, **Try again**. - **Part of a page loads.** A call sheet with its schedule but not its locations shows the sheet with the missing block marked, never blank fields that look like real blanks. - **A sample project.** Ships inside the app, so looking needs no account and no network (Decision 0035, part 2). - **Import interrupted.** "Import needs attention" with the reason; what was imported stays. ## Phone and desktop The same states. On a phone the quiet line sits where the first card would be, under the one-line header, and the progress toast sits above the floating button. A long import on a phone keeps running if the screen locks, and says on return how far it got. ## Writing - Name the thing: "Opening the script…", "Opening the desk…", "Opening the board…". - Use the ellipsis character for work in progress: "Saving…", "Exporting…". - Progress: "Importing Blank Pages: 64%", "48 of 112 pages". - No "Please wait", "Hang tight", "Loading data", or jokes. ## Accessibility - The loading area carries `aria-busy="true"`; skeleton shapes are `aria-hidden`. - The quiet line is in a polite live region, so a screen reader hears what is opening once. - Progress uses a native `progress` element with a label, or `role="progressbar"` with `aria-valuenow`. - Focus is not moved by content arriving, unless the person asked for it (opening a scene). **Do:** "Opening the script…" in the content area, with the header and tools already in place. **Don't:** A blank white screen with a centred spinner, then "No scenes yet" for a second before the scenes arrive. **Do:** A project that has not downloaded opens read-only with the banner and **Try again**. **Don't:** A project that has not downloaded opens an empty editor that autosaves. ## Demo ```html
Opening the desk…
Preparing print preview
48 of 112 pages
``` ## Related [Skeleton](https://kwark.space/designSystem/components/skeleton.md), [Spinner](https://kwark.space/designSystem/components/spinner.md), [Progress](https://kwark.space/designSystem/components/progress.md), [Toast](https://kwark.space/designSystem/components/toast.md), [Saving and sync](https://kwark.space/designSystem/patterns/saving-and-sync.md), [Empty states](https://kwark.space/designSystem/patterns/empty-states.md), [Motion](https://kwark.space/designSystem/foundations/motion.md). ## AI readiness test **Task:** The Budget shows "No budget lines yet" for a second before lines appear. **Give the agent:** This page, Empty states, Saving and sync. **Constraint:** No new listeners. **A reliable answer:** - Adds a loaded flag so the empty state shows only after data has arrived - Shows "Opening the budget…" or a skeleton of rows in the content area, with the header in place - Ensures nothing saves until loaded - Keeps the skeleton still under reduced motion --- # Menus and shortcuts > 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. Source: https://kwark.space/designSystem/patterns/menus-and-shortcuts ## The problem A screenwriter who has used professional screenwriting software for ten years reaches for the menu bar without looking. In October 2026 Kwark's editor had seven menus, a stopwatch in the header, a Tools menu that repeated the side rail, a Production menu with greyed items and code names, and four different words for saving a moment in time. On a phone, the same commands were a sheet of 62 rows that silently dropped every submenu. Earlier, the founder had rejected menus built as piles of checkboxes under quirky headings ("How the page reads") as "a lazy way to hand out options" and asked where the settings were. Menus are where a professional judges whether a tool is serious. They are also the one place every command must be findable by someone who does not know Kwark's internal names. ## Kwark's answer ### Five menus, one list for every screen (Decision 0015) **File · Edit · Format · View · Help.** Each command has one home. Panels live in View › Panels (and on the rail). Removed: Tools, Production, the header stopwatch, the automatic tour offer and the Writing insights switch in the menu. Names were made plain: **Restore points** (not snapshots), **Prepare to shoot** (Decision 0009), **Room**. | Menu | What lives there | |---|---| | File | Drafts…, New draft from this one, Import as a new draft…, Title page, Keep a restore point, Restore points…, Revisions and locking…, Export…, Delivery…, Reports…, Settings… | | Edit | Undo, Redo, Cut and keep, Select all, Find and replace, Go to scene…, Comments, Quick note, Rename a character…, Change case (UPPERCASE, lowercase, Title Case), Move line up, Move line down | | Format | This line is (Scene heading, Action, Character, Dialogue, Parenthetical, Transition, Music, Shot, Lyrics), Dual dialogue, Page break, On screen, Align action, Structure (Act, End of act, Sequence, Montage, Series of shots, End of group) | | View | Read mode, Focus (Off, Distraction-free, Dialogue focus), Around the page (Scenes, Timeline, Ruler), Zoom (Zoom in, Zoom out, Actual size, Fit width, Fit page), On the page (Scene numbers, Character colours, Translations), Room…, Panels, Prepare to shoot beside the page (Breakdown, Shot list, Schedule) | | Help | Keyboard shortcuts, What each panel does, Take the tour | ### Desktop-grade items Built from the `components/menu/Menu.tsx` primitives: - **A shortcut on the right**, from `utils/editorShortcuts.ts`, the one file that defines what the menus show, what the shortcuts sheet lists and what the keys do. - **A switch** for anything that stays on (Scenes, Timeline, Ruler). - **Radio items** for one of several (Focus: Off, Distraction-free, Dialogue focus). - **A tick on the right** marks the chosen option. **A chevron** means it opens a page or a flyout. **An ellipsis** in the label means it opens a dialog that asks for more. - Anything chosen once and kept goes to the **Settings** window, not the menu. See [Settings](https://kwark.space/designSystem/patterns/settings.md). ### The shortcuts Real, from `editorShortcuts.ts`. Shown as ⌘ on a Mac and Ctrl elsewhere (⌥ is Alt, ⇧ is Shift). Keys a browser keeps for itself (new tab, close, reload) are left alone. | Command | Mac | Windows and Linux | |---|---|---| | Settings… | ⌘, | Ctrl+, | | Keyboard shortcuts | ⌘/ | Ctrl+/ | | Save (says "Saved. Your script saves as you write.") | ⌘S | Ctrl+S | | Keep a restore point | ⇧⌘S | Ctrl+Shift+S | | Export… | ⇧⌘E | Ctrl+Shift+E | | Find and replace | ⌘F | Ctrl+F | | Go to scene… | ⌘G | Ctrl+G | | Scenes (the scene navigator) | ⌘\ | Ctrl+\ | | Read mode | ⌥⌘R | Ctrl+Alt+R | | Distraction-free | ⇧⌘F | Ctrl+Shift+F | | Undo | ⌘Z | Ctrl+Z | | Redo | ⇧⌘Z | Ctrl+Shift+Z | | Dual dialogue | ⇧⌘D | Ctrl+Shift+D | | Cut and keep | ⌥⌘X | Ctrl+Alt+X | | Select all | ⌘A | Ctrl+A | | Quick note | ⌥N | Alt+N | | Move line up, down | ⌥↑, ⌥↓ | Alt+↑, Alt+↓ | Elements answer to Shift+Cmd and a digit (Ctrl+Shift elsewhere): 1 Scene heading, 2 Action, 3 Character, 4 Dialogue, 5 Parenthetical, 6 Transition, 7 Music, 8 Shot, 9 Lyrics. A writer can give a digit to another element in **Settings › Keyboard**; the new meaning works at once, and a digit given to two elements belongs to the later choice. Cmd+S is a promise kept, not a command (Decision 0014): writers press it out of habit, so it reassures and changes nothing. A restore point is a deliberate act with its own keys. ### On a phone The same five menus, as a Menu sheet. It opens on **Showing** (Script, Title page, the Prepare to shoot views), then Find, Read, Export, Quick note, Comments, then File, Edit, Format, View and Help, each drilling to its own page with a labelled back row. Shortcuts are not shown on a phone; a one-line hint is, where the name alone is not enough. ### Context menus and row menus Right-click (or long-press, or the row's ⋯) opens a menu of actions on that thing: Scene 12, a character, a story on Home. It follows the same item rules and puts the destructive action last, after a separator, in danger text. ## Anatomy | Part | Means | |---|---| | Label | A verb and object, or the thing it shows: "Keep a restore point", "Timeline" | | Shortcut | Right-aligned, quiet text, platform keys | | Tick | The chosen option among several | | Switch | A view that stays on until switched off | | Chevron | Opens a page or a flyout | | Ellipsis in the label | Opens a dialog that needs more input | | Separator | A new group of related commands | | Dot on Menu (phone) | Comments for you | | Dot on View | A focus mode is on | | Greyed row | Only while the page is read-only; the reason is written at the top of Edit and Format ("Read-only while a pre-production view is open") | ## Rules - **Must** give every command exactly one home among the five menus; the rail may repeat panels only. - **Must** take shortcut labels from `utils/editorShortcuts.ts`; never type a shortcut into a label by hand. - **Must** show platform keys: ⌘ on a Mac, Ctrl elsewhere. - **Must** use a switch for persistent views, radio items for one-of-several, and a tick for the chosen one. - **Never** add a menu for one feature. A new command goes into File, Edit, Format, View or Help. - **Never** show greyed items that will never work here. Hide them, or show the reason. - **Never** take a key the browser uses for itself (Cmd+T, Cmd+W, Cmd+R). - **Never** build a menu as a pile of checkboxes under a heading. Choices that are kept go to Settings. - **Always** keep the same order and names on phone and desktop. - **Always** put a destructive item last, after a separator, and confirm or offer Undo as [Destructive actions](https://kwark.space/designSystem/patterns/destructive-actions.md) says. ## Edge cases - **Read-only.** Edit and Format show the reason at the top and grey only what cannot work; View and Help stay live. - **Export not allowed.** The item stays, disabled, with the hint "Export disabled by project owner". - **Non-Latin keyboards.** Shortcuts match the key's place on the keyboard when the character differs (⌥R types ®; ⇧/ types ?), so they work in Hindi or Tamil layouts. - **A series.** Episode navigation (Previous episode, Next episode, All episodes) joins the existing menus; no new menu is added. - **The writer reassigns a digit** that another element used: that element loses it, and the shortcuts sheet shows the new map. ## Writing - Plain names a writer would say: "Keep a restore point", not "Snapshot"; "Go to scene…", not "Jump"; "Room…", not "Theme". - Ellipsis only when a dialog follows. - Sentence case, except Change case items, which show their own effect: UPPERCASE, lowercase, Title Case. ## Accessibility - The menu bar is `role="menubar"`; menus are `role="menu"` with `menuitem`, `menuitemcheckbox` (switches) and `menuitemradio` (radio items), and `aria-checked` on both. - Arrow keys move within and between menus; Escape closes and returns focus to the trigger. - The shortcut is part of the accessible description, not the name. - Every shortcut has a menu path; no command is keyboard-only or mouse-only. **Do:** **Keep a restore point**, ⇧⌘S, in File; ⌘S says "Saved. Your script saves as you write." **Don't:** ⌘S makes a "snapshot", the File menu says "Save version", and Edit has "Checkpoint". **Do:** View › Focus with three radio items: Off, Distraction-free, Dialogue focus. **Don't:** A "How the page reads" heading with six checkboxes under it. ## Demo ```html
⇧⌘4 Dialogue ⌘G Go to scene… ⌥N Quick note
``` ## Related [Menu](https://kwark.space/designSystem/components/menu.md), [Keyboard key](https://kwark.space/designSystem/components/keyboard-key.md), [Command palette](https://kwark.space/designSystem/components/command-palette.md), [Sheet](https://kwark.space/designSystem/components/sheet.md), [Settings](https://kwark.space/designSystem/patterns/settings.md), [Phones](https://kwark.space/designSystem/patterns/phones.md), [Saving and sync](https://kwark.space/designSystem/patterns/saving-and-sync.md). ## AI readiness test **Task:** Add a "Number the dialogue for dubbing" command to the screenplay. **Give the agent:** This page, Decision 0015, utils/editorShortcuts.ts, Settings. **Constraint:** No new menu; no browser-reserved keys. **A reliable answer:** - Puts the one-off action in File › Export options or the persistent display as a switch in View › On the page, with a reason - Adds any shortcut in editorShortcuts.ts so menu, sheet and key agree - Shows ⌘ on Mac and Ctrl elsewhere - The phone sheet gets the same item with a one-line hint and no shortcut --- # Navigation > 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. Source: https://kwark.space/designSystem/patterns/navigation ## The problem A director is in the Breakdown for Scene 12 and wants to see whether the props she just tagged reached the Schedule. In the old Kwark she had to back out to the project page, find Prepare to shoot, and go in again. The trail at the top looked different in every module: Prepare to shoot drew its own switcher with menu rows centred down the middle; some Write modules showed a trail with no switcher; one screen showed two trails nested inside each other. At the same time, a first-time writer did not know where to go at all. The phases were called "Understanding" and "Pre-production": not a pair, and jargon to someone who just wants to write. Navigation has two jobs in Kwark: say where you are in words a writer uses, and let you move to the neighbour you need without going home first. ## Kwark's answer ### One ladder Everything sits on one ladder, named in plain words: **Home** (your library) › **Project** (one film, series or franchise) › **Phase** (Write or Prepare to shoot) › **Module** (Outline, Breakdown…) › **Page** (Scene 12, Day 3, Mira). A franchise adds one rung between Home and the project. Nothing else does. The audit dropped "Personal", "workspace", "Studio" and "story" as container names in menus; a production house is the owner of projects, shown on Home, not a rung of its own. ### Two phases: Write and Prepare to shoot (Decision 0009) User-facing labels are **Write** and **Prepare to shoot**. "Understanding" survives only as a code name (`?phase=understanding`). The words say what the person is doing, and they are a pair. **Write** holds: Screenplay, Outline, Characters & Locations, World & Lore, Idea & Themes, Research, Pitch, and Episodes for a series. **Prepare to shoot** groups its modules by how tightly they are bound to the screenplay: | Group | Line shown | Modules | |---|---|---| | Bound to the script | Rebuilt from the screenplay as it changes. | Breakdown, Shots & Boards, Schedule & Call Sheets, Calendar | | Departments | Each reads its part of the breakdown. | Camera & Light, Art, Costume & Makeup, Sound & Music, Stunts & Effects, VFX (only the desks this film has) | | Draws on the script | Its own records, using the script's people and places. | Filming locations, Cast & Crew, Budget, Paperwork | | Stands on its own | The director's thinking and the film's look. | Director's Book, Look Book | ### Opening a project goes to project home (Decision 0018) A tap on a story on Home opens **Project home** by default: the poster, the phases and their modules, where work stopped. Some writers want to land straight on the page, so Project settings has one choice, **When I open a project: Project home** (default) **/ Where I left off**. The explicit **Continue writing** button always goes to where work stopped. The default orients; the shortcut for returning writers is one setting away. ### One breadcrumb (Decision 0044) Every breadcrumb in the app is drawn by `components/ui/Breadcrumb.tsx`, styled only by `--k-crumb-*` tokens, and built by one trail builder (`buildModuleTrail` with `ProjectModuleBreadcrumb`): `Home ▸ [Franchise ▸] Project ▸ Phase ▾ ▸ Module ▾ [▸ Sub-page ▾]` - The **Phase** dropdown switches between Write, Prepare to shoot, and **Back to the project**. - The **Module** dropdown lists the sibling modules the person is allowed into, in the active phase, grouped as above in Prepare to shoot. - A **non-last** crumb that has both a destination and a dropdown is split: the label navigates, only the chevron opens the menu. - The **last** crumb (where you are) opens its dropdown wherever you click it. - Menus open as portals, stay inside the viewport, align icon and label to the left, and answer Arrow Up and Down, Home, End, Enter, Space, Escape and Tab. - Past five segments, the middle collapses into an ellipsis; never before. **No breadcrumb** on: the screenplay editor (it has its five menus, Decision 0015), the shot listing workbench (a dense single-row toolbar), phones (they use a one-line header, Decision 0016), and Home, sign-in, About and this design system. ## Anatomy | Part | Means | |---|---| | Home crumb | Your library. Never labelled with a product or company name. | | Project crumb | The project's name, as the writer wrote it, truncated with an ellipsis at the end. | | Phase crumb and chevron | Which phase; the chevron opens the phase switcher. | | Module crumb and chevron | Which module; the chevron opens its siblings. | | Current crumb | `aria-current="page"`; full contrast; opens its own menu. | | Separator | A quiet chevron, hidden from screen readers. | ## Rules - **Must** render every app breadcrumb through the shared `Breadcrumb` component and the shared trail builder. The build enforces it. - **Must** use the words Write and Prepare to shoot wherever a phase is named: hub, tabs, breadcrumbs, menus. - **Must** offer only modules the person is allowed into in the module switcher. - **Must** open a project on Project home unless the person chose Where I left off. - **Never** centre menu rows; icon and label align left. - **Never** draw a second, local trail inside a module that already has the shared one. - **Never** show a breadcrumb on a phone; show back and the one-word title. - **Never** use internal names in navigation: no "Understanding", "creative lock", "scene database", "visual language". - **Always** keep the person's place: back returns to the scroll position and selection they left. - **Always** use the names on the cards: Shots & Boards, Director's Book, Look Book, Camera & Light, Costume & Makeup, Filming locations (Decision 0034). ## Edge cases - **A module the person cannot open.** It is left out of the switcher. If they arrive by link, they see "{Owner} hasn't shared {module} with you." with **Back to the project**. - **A series.** Episodes join Write's module list and the screenplay shows the episode in its own dropdown. - **A very long project name.** Truncate the project crumb at the end with an ellipsis; the full name is in its tooltip and accessible name. - **A department this film does not have.** Its desk is not listed. Desks that would reach an unbuilt page are hidden, never shown as "still being built". - **Deep pages.** Scene 12 inside Shots & Boards adds one sub-page crumb with its own dropdown of neighbouring scenes. ## Phone and desktop On a phone there is no breadcrumb. The header is one line: back chevron, one-word title, **Menu ▾** (see [Phones](https://kwark.space/designSystem/patterns/phones.md)). The Menu sheet carries what the breadcrumb's dropdowns do on desktop: switch phase, switch module, back to the project, each as a row that drills down one page. On tablet and desktop the breadcrumb is one 32px bar under the app header. ## Writing - Phase names: **Write**, **Prepare to shoot**. The switcher's last row: **Back to the project**. - Setting: **When I open a project** · **Project home** · **Where I left off**. - Buttons on Home's desktop rows: **Project home**, **Continue writing**. - Module names as on their cards, with "&" where the card uses it. ## Accessibility - The trail is a `nav` with `aria-label="Breadcrumb"`; the current item has `aria-current="page"`. - Dropdown triggers carry `aria-haspopup="menu"` and `aria-expanded`; a split crumb has two focus stops (the link, then the chevron button named "Choose module" or similar). - Menus trap arrow keys, close on Escape, and return focus to their trigger. - Separators are `aria-hidden`. **Do:** `Blank Pages › Prepare to shoot ▾ › Breakdown ▾`: the chevron on Breakdown lists Shots & Boards and Schedule & Call Sheets, so the director moves sideways in one step. **Don't:** A Back to project link as the only way out, so every move between modules goes through the hub. **Do:** Phase switcher rows with icon and label aligned left. **Don't:** Rows centred in the popover, so icons and labels drift down the middle. ## Demo ```html
When I open a project
``` ## Related [Breadcrumb](https://kwark.space/designSystem/components/breadcrumb.md), [Page header](https://kwark.space/designSystem/components/page-header.md), [Menu](https://kwark.space/designSystem/components/menu.md), [Phones](https://kwark.space/designSystem/patterns/phones.md), [Menus and shortcuts](https://kwark.space/designSystem/patterns/menus-and-shortcuts.md), [Sharing and roles](https://kwark.space/designSystem/patterns/sharing-and-roles.md). ## AI readiness test **Task:** Add the new Paperwork module's pages to navigation. **Give the agent:** This page, Decisions 0009, 0018, 0044, components/ui/Breadcrumb.tsx. **Constraint:** No new breadcrumb code. **A reliable answer:** - Uses buildModuleTrail and ProjectModuleBreadcrumb, not a local trail - Lists Paperwork under Draws on the script in the module switcher, only for people allowed in - Sub-pages get one crumb with a sibling dropdown - Phone shows back, "Paperwork" and Menu, no breadcrumb - Uses Prepare to shoot, never Pre-production, in visible text --- # Notifications > 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. Source: https://kwark.space/designSystem/patterns/notifications ## The problem A writer is three pages into the hardest scene of her film. A toast slides in to say a co-writer resolved a comment. A badge pulses on a bell. A red dot appears on an avatar. None of it needs her now, and each one pulls her out of the page. Most software treats notifications as a growth tool: streaks to protect, digests to open, red counts to clear. Kwark's mission rules that out in plain words: "No notifications that exist to bring people back." And the calm test asks of every screen: does anything ask for attention it has not earned? But some things do need a person: someone is waiting to be let into the project, a revision was issued, an action can be undone for a few seconds, their words have not reached the cloud. Those must be told clearly, in the right place. ## Kwark's answer ### Tell only what earns it A notification is allowed when it is one of these: | Kind | Example | Form | |---|---|---| | The result of what you just did | "Rev 3 issued. Save it as PDF to send it to the crew." | Toast | | Something you can undo for a moment | "Cover removed." **Undo** | Toast with action, 8 seconds | | Someone is waiting for you | "People asking to join" | The bell, with a count | | Someone spoke to you | "Someone mentioned you" | In the comment dock, and a dot | | Your work is not where you think | "Saved on this device" | The sync word, and a banner if you must act | | Something on this page needs you before it can continue | "Location to be confirmed. Add it before issuing the call sheet." | Inline notice | Everything else is not said. A co-writer resolving a comment, someone opening the project, a save that worked: these are visible where they happened, if you look, and nowhere else. ### Kwark sends no email Kwark has no mail sender. Sharing says so and gives the owner **Copy invite message** and **Email the invite** from their own mail app (Decision 0042). Emailed crew-call invitations with calendar files are written and tested but on hold, and nothing is deployed; the button to send them stays hidden until a mail sender exists. **Never** write "We'll email you" or "Invitation sent" anywhere in Kwark. ### The bell is for people waiting The only bell in Kwark is `AccessRequestsBell`: people asking to join any of your projects. Its bubble (accent) is the number waiting. Opening it lists "People asking to join" with **Keep**, **Decline** and **Open project**. It does not pulse (Decision 0042 removed the pulse). If an answer could not be saved: "That request was not answered. Open the project and try from Share." ### Dots, each with a reason Every dot has a row in the element register saying what it means and what to do: - **Dot on the floating button (phone)**: comments waiting for you. It is the button's only badge (Decision 0016). - **Dot on the screenplay's Menu**: comments for you (Decision 0015). - **Dot on View**: a focus mode is on. - **Bubble on the bell**: people asking to join. A dot with no reason is removed. ### Toasts From `components/ui/Toast.tsx`: - Four tones: success, info, warning, error. Each has words; the tone supports them. - Dismiss after **4 seconds**, or **8 seconds** when there is an action (such as Undo). The timer pauses on hover and focus. - At most one action, named with its verb. - `role="status"` for ordinary toasts; `role="alert"` for errors. - Bottom right on desktop; above the floating button on a phone. ## Anatomy | Part | Means | |---|---| | Toast | Something just happened because of you | | Toast action | One reversible step, usually Undo | | Bell and bubble | People waiting to be let in; the number is how many | | Mention row in the dock | Remarks that name you; **Show** | | Dot | One recorded meaning, per surface | | Banner | A state that stays until it changes | | Inline notice | This part of this page needs something | ## Rules - **Must** tie every notification to something the person did, is waiting on, or must act on. - **Must** put every dot, badge and count in the element register with its meaning. - **Must** give toasts words, one action at most, and the 4 or 8 second timing with pause on hover and focus. - **Never** notify to bring people back: no streak reminders, no "You haven't written in a while", no digests, no "what's new" pop-ups. - **Never** promise email or say anything was sent. Kwark sends no email. - **Never** pulse, bounce, glow or shake a badge. - **Never** use red for a count. A count is not a danger. - **Never** interrupt the page while someone writes for anything that can wait. The screenplay hides the app's floating pen and comments bubble in favour of its own rail and Menu entries. - **Always** say the result in the words the action used: Issue, "Rev 3 issued"; Move to trash, "Moved to trash". - **Always** show a count only where it is useful: Home's tabs show a count only on the selected tab (Decision 0021). ## Edge cases - **Many toasts at once** (a batch of imports). Stack at most three; combine the rest into one ("3 projects imported"). - **A toast during a sheet or dialog.** It appears above the sheet, never under it, and never steals focus. - **The person is offline.** Do not toast every queued save; the sync word carries it. - **A mention while writing in the screenplay.** The dot appears on Menu; nothing slides over the page. - **Access ended.** Not a toast. The person sees the named access-ended page when they next open the project. - **Quota reached for the day.** Say it once, as a quota, not a fault in their change. ## Phone and desktop Desktop: toasts bottom right, the bell in the app header, mentions in the comment dock beside the page. Phone: toasts sit above the floating button's slot and span the width minus the gutters; the bell keeps its place in the app chrome and must never collide with the one-line header or the floating button; the dot on the floating button is the only badge on screen. ## Writing - Results: "Rev 3 issued. Save it as PDF to send it to the crew." "Copied. Paste it into WhatsApp or an email." "Story restored" / "It is back in your library". - Requests: "People asking to join", **Keep**, **Decline**, **Open project**. - Mentions: "Someone mentioned you", "{n} remarks mention you", **Show**. - No "Success!", "Yay", "Oops", or exclamation marks. Legacy toasts such as "Account created successfully" with an exclamation mark, or "Failed to delete", are deviations to fix. ## Accessibility - Toasts are in a polite live region; error toasts use `role="alert"`. - A toast's action is reachable by keyboard before it dismisses, and focusing it pauses the timer. - The dismiss button is named for what it dismisses ("Dismiss notification"). - Dots and bubbles have text equivalents in their control's name: "Comments, 2 waiting", "People asking to join, 1". **Do:** "Cover removed." with **Undo** for 8 seconds, pausing on hover. **Don't:** "Success!" in green, gone in 2 seconds, with nothing to do. **Do:** A bubble with "1" on the bell when Asha asks to join; it never pulses. **Don't:** A pulsing red badge for every comment resolved by anyone. **Do:** After inviting: "Kwark doesn't send emails. Let them know, and say which Google account to use." with **Copy invite message**. **Don't:** "Invitation sent" when no email was sent. ## Demo ```html
Moved to trash.
Story restored. It is back in your library.
``` ## Related [Toast](https://kwark.space/designSystem/components/toast.md), [Badge](https://kwark.space/designSystem/components/badge.md), [Status dot](https://kwark.space/designSystem/components/status-dot.md), [Banner](https://kwark.space/designSystem/components/banner.md), [Collaboration](https://kwark.space/designSystem/patterns/collaboration.md), [Sharing and roles](https://kwark.space/designSystem/patterns/sharing-and-roles.md), [Errors](https://kwark.space/designSystem/patterns/errors.md). ## AI readiness test **Task:** The founder's co-writer asks for a notification when a scene is changed. **Give the agent:** This page, the mission ("What we will not do"), Collaboration, the element register. **Constraint:** Nothing that exists to bring people back. **A reliable answer:** - Asks what they need to act on (a review request, a mention) rather than notifying every change - Proposes a mention or a comment pin in the place it concerns, with the dot recorded in the register - No email (none is sent), no feed, no pulsing badge - Leaves change marks in the script as the record of what changed --- # Onboarding without teaching > 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. Source: https://kwark.space/designSystem/patterns/onboarding-without-teaching ## The problem Kwark has a lot in it: a screenplay editor with five rooms, an outline, characters, research boards, a breakdown, shots and boards, a schedule, call sheets, a budget. A new writer needs to find the parts she wants without being walked through the parts she does not. A working director needs none of it explained. Two habits of software make this worse. One is the tour that opens itself, covers the page with arrows, and has to be dismissed before you can type. The other is the coach: empty fields that ask "What does your hero want more than anything?", sliders for "tension", panels that explain what a push-in "means". Kwark's founder rejected both. On teaching: "structure is our usp, not teaching them." On menus full of explanation: "a lazy way to hand out options". Kwark's people are students and part-time professionals. They need working structure and a tool that gets out of the way, not film school. ## Kwark's answer ### Two kinds of help, and only one is allowed | Help about Kwark's own controls | Teaching the craft | |---|---| | "Dual dialogue: Two people speaking at the same time" | "Use dual dialogue to show tension between characters" | | "Fit width: The page as wide as the window" | "A wider page helps you see rhythm" | | "Writing insights: The character's card beside a cue… Off by default." | "Track your character's arc to keep readers engaged" | | Allowed | Never (Decision 0004) | Help may say what a control does and where its result goes. It never says how to write, what makes a scene good, or what a choice "means". ### Onboarding is the product being clear Most of what other tools do with onboarding, Kwark does with ordinary design: - **Plain names.** Restore points, not snapshots; Prepare to shoot, not Pre-production; Shots & Boards, not "scene database". A name that needs explaining is the wrong name. - **Honest empty states** that say where content comes from: "The schedule is built from the screenplay's scene headings. Write or import the script, and every scene arrives here as a strip." See [Empty states](https://kwark.space/designSystem/patterns/empty-states.md). - **Hints where a name is not enough**, on phones in the Menu sheet: "Keep a restore point: A point inside this draft you can go back to." - **Settings rows with a line of meaning**: "Finish transitions: The rest of a transition shown faint as it is typed; Tab takes it." - **A sample film** to look at, not to be walked through (Decision 0035). - **The first frame**, which shows what one script becomes in five real pieces, then gets out of the way. See [First run](https://kwark.space/designSystem/patterns/first-run.md). ### Help on demand, in one menu The screenplay's **Help** menu holds three things, and they appear only when asked for: - **Keyboard shortcuts** (⌘/): every key, from the one file that defines them, and the element digits the writer can reassign. - **What each panel does**: one line per panel. - **Take the tour**: "Two minutes round the room, on the room itself." The tour never opens on its own; the automatic offer was removed (Decision 0015). Open work, recorded in Decision 0015: the tour has fifteen chapters and is to be cut to five, and the separate "Learn the room" guide is to be removed, because its "How the page reads" heading is exactly the kind of menu-as-lesson the founder rejected. ### Structure waits to be chosen Structure features are off until the writer turns them on, and each is one switch away (Decision 0003). Kwark does not nudge toward them. A writer who only wants to write gets an empty page and a blinking cursor. ### Coaching that was removed These were in Kwark and are gone or going under Decision 0004: the Enneagram quiz, "Engine of…" text, tension sliders, camera "meaning" engines, the Director's Manifesto's rhetorical prompts, Idea "Conviction" percentages, Outline "Finder" trophies, and the empty outline card's story-position questions (removed 4 November 2026; it now says "Add words…"). ## Anatomy | Part | Where | Says | |---|---|---| | Name | Everywhere | What it is, in the person's words | | Hint | Phone menu rows, Settings rows, field hints | What it does or where the value goes | | Empty state | Any empty module | What goes here and where it comes from | | Help menu | Screenplay, last menu | Shortcuts, panels, the optional tour | | Tour | On request | The room itself, briefly; skippable at every step | | Sample film | First frame, About | A real film to look at, read-only | ## Rules - **Must** explain only Kwark's own controls, and only where a plain name is not enough. - **Must** keep the tour optional: started only from Help, skippable at every step, never blocking typing. - **Must** say where a value goes, not why it matters to the story. - **Never** open a tour, a coach mark, a tooltip sequence or a "what's new" dialog on its own. - **Never** put craft questions, prompts or examples of good writing in fields or empty states. - **Never** add a "Learn more" lesson about filmmaking beside a field. - **Never** reward exploring with badges, progress rings or a checklist ("3 of 7 steps done"). - **Always** prefer renaming a control to explaining it. - **Always** keep help in one place per surface (the Help menu, the Settings line), not scattered as popovers. ## Edge cases - **A brand-new feature.** Announce nothing. If people need to know, the release notes say it, and the feature's name and empty state make it findable. - **A complex tool (the Camera & Light gates and sun).** Label each control plainly and give its result a visible place on the page; the skeuomorphic camera gear is the explanation. - **A writer who asks for teaching.** That would be a separate, opt-in place, if the evidence ever came (Decision 0004 names this as what would make us revisit it). It is not built. - **A phone.** Hints replace keyboard shortcuts in the Menu sheet; the tour is the same chapters, sized for one hand. - **Read-only collaborators.** They see the same names and help, minus controls they cannot use; nothing explains a feature they cannot reach. ## Phone and desktop On desktop, help lives in the Help menu and in Settings' row lines; tooltips name icon buttons. On a phone there are no hover tooltips, so every icon has a word, and the Menu sheet rows carry a one-line hint where needed. The tour on a phone sits at the bottom of the screen, never covering the line being written. ## Writing - Hints describe the effect: "The running time of the script laid out end to end." - Say "Off by default." when a feature is off by default, so people know it is a choice. - The tour's voice is the app's: plain, brief, no exclamation marks, no "Let's get started". - Tour chapter titles name things: "Every kind of line, by name", "Every scene, down the side", "The film, end to end". ## Accessibility - Help never depends on hover: every hint is visible text or an accessible description. - The tour is a non-modal region; the page stays reachable, focus is not trapped, and Escape ends it. - Keyboard shortcuts are listed as text in the sheet, not only drawn as keycaps. **Do:** **Dual dialogue**, hint "Two people speaking at the same time". **Don't:** A coach mark that pops up on first use: "Pro tip: dual dialogue creates tension." **Do:** An empty outline card that says "Add words…". **Don't:** An empty outline card that asks "What does an ordinary day look like before anything changes?" **Do:** **Take the tour** in Help, two minutes, skippable. **Don't:** A tour that opens on first launch and must be finished before the page can be typed on. ## Demo ```html
Finish transitions
The rest of a transition shown faint as it is typed; Tab takes it.
Writing insights This project
The character's card beside a cue, and the markers on a speech that open what it is doing.
``` ## Related [First run](https://kwark.space/designSystem/patterns/first-run.md), [Empty states](https://kwark.space/designSystem/patterns/empty-states.md), [Settings](https://kwark.space/designSystem/patterns/settings.md), [Menus and shortcuts](https://kwark.space/designSystem/patterns/menus-and-shortcuts.md), [Structure, not teaching](https://kwark.space/designSystem/method/structure-not-teaching.md), [Tooltip](https://kwark.space/designSystem/components/tooltip.md). ## AI readiness test **Task:** Writers cannot find the Timeline. Make it discoverable. **Give the agent:** This page, Decision 0003, Decision 0015, Menus and shortcuts. **Constraint:** No automatic tour, coach mark or nudge. **A reliable answer:** - Checks the name and its home (View › Around the page › Timeline) before adding help - Adds or improves a one-line hint ("The running time of the script laid out end to end.") - Adds it to the tour chapters without making the tour automatic - Leaves the Timeline off by default and switchable --- # Phones > 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. Source: https://kwark.space/designSystem/patterns/phones ## The problem Kwark's people write on phones: on the train home after a shift, between takes, in a queue. On 17 October 2026 the founder opened the Outline on his phone and found a two-line header (title and story name), account and comments icons, then three rows of controls (New Act, Cards, Find a beat, All beats, Pad, More) before any writing. Characters still showed a desktop breadcrumb running under the comments icon. His words: "80% of the page is non-writing stuff … header everywhere is bad … no breadcrumb, just a back button … comment, account and edit under one FAB at the bottom … do we need 2 lines in the top banner?" The same week, Home on a phone showed a search box, New project, three filter chips, a sort arrow and two buttons on every story row; each row was about 160px and the first story sat low. And when a run-the-app audit measured the production office at 375 wide with real touch, 252 controls on 11 screens were smaller than 44px. A phone has no space to waste, and a thumb is not a mouse pointer. ## Kwark's answer ### One line at the top, one button at the bottom (Decision 0016) 1. **The header is one line, about 44px:** a back chevron, a one-word screen title, and a labelled **Menu ▾** button. No subtitle, no breadcrumb, no account or comments icons. 2. **Comments, Quick note and Account live in one floating button** at the bottom corner. It opens a small dial of labelled 44px items: **Comments**, **Quick note**, **Account**. A dot on it means comments are waiting for you; that is its only badge. The page keeps a reserved slot at its foot (`--k-fab-slot`) so the button never covers content, and the button steps aside while comments, a note or a sheet is open. 3. **A screen's own tools collapse** into one compact row or into Menu, so the writer's content starts by about y = 120 on a 375 × 812 screen. The Outline went from y≈392 to y≈222 in the first fix round; y≈120 still needs the act and view bar folded into the header. 4. **Desktop is unchanged.** The bottom corner is where thumbs are. And moving occasional actions out of the top-right fixed a whole class of collision bugs in which icons sat on top of each other. ### Home: the projects take the attention (Decision 0021) - One bar: **Yours** and **Shared** tabs (a count only on the selected one) and four labelled icons: **Search**, **Filter and sort**, **New project**, and ⋯. A second band appears only while searching. Cards and List moved into ⋯. - A story row has **no buttons**. Tapping it opens the project as Decision 0018 says (Project home, or Where I left off). A row is about 103px. - The row's ⋯ menu leads with **Project home** and **Share** (yours only), then Edit, Export, Move and Move to trash. **Open in new tab** is not offered on a phone. ### The screenplay on a phone - The editor uses one compact query everywhere: `(max-width: 767px), (pointer: coarse) and (max-height: 520px)`. A phone held sideways gets the phone layout. A test fails if a rule reverts to a bare `max-width: 767px`. - The five menus become a Menu sheet that opens on **Showing** (Script, Title page, the Prepare to shoot views), then Find, Read, Export, Quick note, Comments, then File, Edit, Format, View and Help, each drilling to its own page (Decision 0015). - The scene list is a labelled **Scenes** button, not an icon. - The timeline rests as a 22px strip under the menu: slide a thumb to scrub, tap to open; turned sideways it opens a full-screen edit bay (Decision 0007). - Zoom offers **Fit width** ("The page as wide as the window") and **Fit page**. ### Thumb-sized everywhere (Decision 0034) On phones, upright or sideways, segments, icon buttons, fields, paperwork statuses, budget rows, desk statuses and notices are 44px targets (`--k-tap`). Buttons can be drawn at about 36px inside a 44px tap area. Office helper text is 12px, not 11. Paper is the exception on purpose: the call sheet, the stripboard strips and anything inside print rules keep their sizes, because changing them changes what prints. After the change the same 11 screens measured 138 small controls, mostly in Shots & Boards and on the call sheet's paper fields; those need their own phone layouts, not smaller rules. ## Anatomy | Part | Size | Means | |---|---|---| | Header | 44px, safe-area inset at the top | Where you are and the way back | | Back chevron | 44px target | Up one rung of the ladder | | Title | One word where possible, truncated with an ellipsis | The screen | | Menu ▾ | Word, icon and chevron | Everything else on this screen | | Floating button | 46px disc, `--k-shadow-pop` (it floats) | Your own shortcuts: Comments, Quick note, Account | | Dot on the floating button | Small, with an accessible count | Comments waiting for you | | Bottom sheet | Grip, title, rows that drill down one page at a time, a labelled back row | A menu or a short form | | Fab slot | Reserved padding at the foot | Content never sits under the button | ## Rules - **Must** use one header line on phones: back, title, at most two labelled actions, and **Menu ▾**. - **Must** start the person's content by about y = 200, aiming for y≈120 on 375 × 812. - **Must** use 44px targets wherever the pointer is coarse. - **Must** use the shared compact query in the screenplay, so sideways phones get the phone layout. - **Must** reserve the floating button's slot so it never covers content or a toast. - **Never** show a breadcrumb, a subtitle, an explanatory sentence or a row of chips above the content on a phone. - **Never** put buttons on a list row; the row opens, and its ⋯ menu holds the actions. - **Never** use "⋯" alone in a header. The word is **Menu**. ("3 dots means nothing", the founder.) - **Never** rely on hover or drag alone. Every hover tip and drag has a tap or menu equivalent. - **Always** make bottom sheets drill down one level per page with a labelled back row, never a 62-row list. - **Always** shrink nothing on paper to fit a phone. Paper prints as paper. ## Edge cases - **320 wide.** Check headers at 320. The title truncates before the Menu button does; Menu never wraps. - **The keyboard is open.** Bottom bars ride above the visual viewport; the floating button hides while a field has focus. - **Sideways phone.** Compact layout, safe-area insets on both sides; the timeline opens as the full-screen bay. - **A notch or home bar.** `viewport-fit=cover` and safe-area insets on the header and any bottom bar; `100dvh`, never `100vh`. - **Android back.** Closes an open sheet before it leaves the page. - **Screens not yet migrated.** A few screens without `PageHeader` keep a fixed top-right fallback; do not copy it. ## Writing - Header: one word. "Outline", "Characters", "Schedule". - **Menu**, never "More" or "⋯". - Dial items: **Comments**, **Quick note**, **Account**. The dial's accessible name: "Comments, quick note and account". - Sheet hints may replace keyboard shortcuts on a phone: Keep a restore point, "A point inside this draft you can go back to"; Dual dialogue, "Two people speaking at the same time". ## Accessibility - The floating button has an accessible name that lists what it opens, `aria-haspopup="menu"` and `aria-expanded`. - The comments dot is mirrored in the accessible name ("Comments, 2 waiting"). - Sheets are modal dialogs: focus moves in, is held, and returns to the trigger; Escape and the back gesture close them. - Text zoom to 200% must not clip the header; the title truncates. - Nothing under 12px on a phone, nothing under 11px anywhere. **Do:** Back, "Outline", **Menu ▾** on one line; the first act card at y≈220; one pen at the bottom corner. **Don't:** "Outline" and "Blank Pages" on two lines, account and comments icons, and three rows of tools before the first card. **Do:** A story row with the poster, title and one line of facts; tap opens it; ⋯ holds Project home and Share. **Don't:** A story row with **Project home** and **Continue writing** buttons at 32px, each 160px tall. ## Demo ```html

Schedule

``` ## Related [Page header](https://kwark.space/designSystem/components/page-header.md), [Floating dial](https://kwark.space/designSystem/components/floating-dial.md), [Sheet](https://kwark.space/designSystem/components/sheet.md), [List row](https://kwark.space/designSystem/components/list-row.md), [Navigation](https://kwark.space/designSystem/patterns/navigation.md), [Menus and shortcuts](https://kwark.space/designSystem/patterns/menus-and-shortcuts.md), [Layout](https://kwark.space/designSystem/foundations/layout.md). ## AI readiness test **Task:** Bring the Budget screen to the phone pattern. **Give the agent:** This page, Decisions 0016, 0021, 0034, Page header, Floating dial. **Constraint:** Desktop unchanged; paper sizes unchanged. **A reliable answer:** - One 44px header with back, "Budget" and Menu - no breadcrumb or subtitle - Account rows are 44px and hold no buttons, actions in a ⋯ sheet - Content starts by about y = 200 at 375 wide, checked at 320 too - The floating slot is reserved - the printed top sheet keeps its sizes --- # Print and export > 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. Source: https://kwark.space/designSystem/patterns/print-and-export ## The problem At 11 p.m. the night before Day 3, the second AD changes the crew call from 07:00 to 06:30 and prints the call sheet. At midnight the location manager corrects the parking. At 5 a.m. half the crew holds one paper and half holds another, and nobody can say which version went out. Before October 2026, Kwark had an "Issued" field that nothing ever set. Meanwhile a writer in Chennai sends her bilingual script to a producer, and every Tamil line in the PDF comes out as broken glyphs. And the line producer asks, reasonably, for the budget in a spreadsheet. Film work runs on paper. A table on a screen is not something a crew accepts on set (Decision 0005), and a PDF that mangles a writer's language, or a call sheet nobody can date, breaks trust in everything else. ## Kwark's answer ### Paper and data from one copy For every module bound to the screenplay, the printable artefact and the structured one are the same thing (Decision 0005). The call sheet on screen is a paper facsimile; the breakdown is the marked-up script and its sheet; the schedule is strips on a board. Printing is first-class: every one of them prints, and the ones a producer needs in a spreadsheet also download as CSV. ### Issue the call sheet: numbered, frozen revisions (Decision 0020) - **Issue Rev N** freezes the current sheet as revision N for that day, holding exactly the printed values. Before the first issue: "Not issued yet. Issuing keeps a numbered copy exactly as it is now." - The working draft stays editable. Its status line says **Matches Rev N. PDF and CSV are ready.** or **Changed since Rev N. Issue again, or choose an issued revision above to save it.** - A viewer switch shows **Working draft** or an issued revision ("Issued Rev 2 by Dev, 17 Nov 23:40"). - **Save as PDF** and **Download CSV** act on the issued revision being viewed, and work on a draft only when it matches the latest revision. Their reason is written on the page when they are disabled, not in a tooltip. - After issuing: "Rev 3 issued. Save it as PDF to send it to the crew." Issuing does not send anything; the words never say it does. - A printed draft carries a **Draft, not issued** stamp. The day's tab shows the newest revision, "Rev 2", replacing the old word "Issued". - Read-only viewers land on the newest issued revision. Locking the sheet was rejected (it stops the person who must fix a call time at midnight). Storing only an `issuedAt` stamp was rejected (it says when, not what). Issued revisions live in their own field, written once per Issue, so ordinary edits never re-upload them. ### Scripts in Indian languages print correctly The PDF library Kwark uses for scripts only sets Latin type, and even with fonts embedded it cannot shape conjuncts or vowel signs that come before a consonant. So a script with any text in the Indian script ranges (U+0900 to U+0D7F) prints through the browser's own **Save as PDF**, from the export preview's pages, with `@page` sized to the paper. Indic lines are set at 0.9× so their vowel signs clear the line above. Notes, alternates and translation appendices are left out of that copy, and the export dialog says so. Latin-only scripts still use the direct PDF. ### The screenplay export **Export…** (⇧⌘E, File menu) opens a preview of the actual pages before anything is written. Its choices, from the app: - **The copy:** Screenplay as written, Story order, Scene outline, For cast, For crew, a draft or a revision. - **Range:** The whole script, or First scene to Last scene, First page to Last page. - **Format:** PDF, .fdx and Fountain. - **Also printed:** Scene numbers ("In both margins"), Change marks ("An asterisk in the margin by every line changed since the last issue"), Dialogue numbers ("D1, D2… beside every speech, for dubbing, ADR and subtitles"), Alternate lines, Script notes, CONTINUEDs. - **Paper colour** for a revision (Blue Revised and the rest), and a header or footer watermark ("Recipient or DO NOT DISTRIBUTE"). - **Indian production** preset. - **Ready to export** before you start; **Exporting…** while it runs; "Nothing would be printed." if the choices exclude everything. Page size is a setting (**Paper**): "The page count, where pages break, the schedule's eighths and the PDF all follow it. A4 holds 60 lines, US Letter 55." Page geometry is measured from the industry's printed pages, so a page in Kwark is a page on paper. ### Files have proper names Exports get a filename a person would give: the project, the document, the day and the revision ("Blank Pages – Day 3 call sheet – Rev 2.pdf"). Names drop control and right-to-left characters and are capped in length. ### CSV is safe to open Every CSV guards against spreadsheet formula injection, including values with leading spaces and full-width characters, so a location called "=HYPERLINK(…)" opens as text. ## Anatomy | Part | Means | |---|---| | Issue Rev N | Freezes the current sheet as revision N | | Working draft / Rev N switch | Which copy you are looking at | | Matches / Changed since | Whether the draft differs from the latest issue | | Save as PDF, Download CSV | Act on the issued copy being viewed | | Rev N tag on the day | The newest issued revision of that day | | Draft, not issued stamp | Printed on drafts only | | Change mark (asterisk in the margin) | A line changed since the last issue | | Export preview | The real pages, before anything is written | ## Rules - **Must** make every crew-facing artefact print as its paper form, from the same copy as its data. - **Must** issue call sheets as numbered, frozen revisions, and keep the draft editable. - **Must** stamp printed drafts "Draft, not issued". - **Must** print scripts with Indian-script text through the browser's print path, and say what that copy leaves out. - **Must** name files properly and guard every CSV against formula injection. - **Never** say issuing "sends" anything. Kwark sends no email. - **Never** shrink paper to fit a phone: paper sizes stay paper sizes (Decision 0034). - **Never** export without a preview of what will be written. - **Always** use the chosen paper size everywhere: page count, breaks, eighths and the PDF. - **Always** write disabled reasons on the page beside Save as PDF and Download CSV. ## Edge cases - **Two devices issue in the same minute.** Both can still write "Rev N" today; the number is the higher of what both fields hold so a stale device does not reuse a number, but a per-revision document is the real fix and is recorded as open. - **An editor rewrites an old revision.** "Frozen" is kept by the app, not the server yet; recorded as open in Decision 0020. - **Contact numbers in frozen revisions** stay after a location is corrected; a purge is planned. - **A call sheet with no hospital or general call.** A calm notice before issuing is planned, not built. - **Mixed Latin and Tamil.** The whole script takes the print path; the dialog explains why notes are not in it. - **US Letter for a co-production.** The writer switches Paper; pages, eighths and the schedule follow. ## Phone and desktop On desktop, issue, PDF and CSV sit above the sheet. On a phone, the issue panel is tall today; PDF and CSV belong in the Menu sheet, which is recorded as open. Printing from a phone opens the system share or print sheet with the same PDF. The paper itself never reflows for a phone; it zooms. ## Writing - **Issue Rev 3**, then "Rev 3 issued. Save it as PDF to send it to the crew." - "Matches Rev 2. PDF and CSV are ready." / "Changed since Rev 2. Issue again, or choose an issued revision above to save it." - "Not issued yet. Issuing keeps a numbered copy exactly as it is now." - **Save as PDF**, **Download CSV**, **Working draft**, **Draft, not issued**. - Export errors: "That copy could not be made. Nothing was changed in your script. Try again, or use a different format." ## Accessibility - The revision switch is a segmented control with the revision's date in its accessible name. - The status line is a polite live region, so "Changed since Rev 2" is heard after an edit. - Exported PDFs from the browser path keep real, selectable text, so screen readers and search work in Tamil and Hindi. - Print styles never rely on colour alone: department colours on a breakdown sheet also carry their names. **Do:** **Issue Rev 3**; the crew's paper says "Rev 3"; the screen says "Changed since Rev 3" after the parking fix. **Don't:** A "Locked" call sheet that the 2nd AD cannot change at midnight, or an "Issued" tick that records nothing. **Do:** A Tamil script printed through Save as PDF with shaped text, and a line saying notes are not in this copy. **Don't:** A PDF with boxes where the Tamil was, and no warning. ## Demo ```html
Issued Rev 2 by Dev, 17 Nov 23:40
Changed since Rev 2. Issue again, or choose an issued revision above to save it.
Blank Pages · Day 3Draft, not issued
Crew call06:30

Edit suite · 17 November · IST

Scenes
ScenePages
12 · INT. EDIT SUITE – NIGHT2⅛
``` ## Related [Call sheet](https://kwark.space/designSystem/components/call-sheet.md), [Screenplay page](https://kwark.space/designSystem/components/screenplay-page.md), [Version history](https://kwark.space/designSystem/components/version-history.md), [Segmented control](https://kwark.space/designSystem/components/segmented-control.md), [Specs and handoff](https://kwark.space/designSystem/method/specs-and-handoff.md), [Writing systems](https://kwark.space/designSystem/foundations/writing-systems.md). ## AI readiness test **Task:** Add PDF and CSV export to the Budget. **Give the agent:** This page, Decision 0005, Decision 0020, Errors. **Constraint:** One copy feeds both; no email. **A reliable answer:** - The printed top sheet and the CSV come from the same values - Filenames like "Blank Pages – Budget.pdf", sanitised and capped - CSV guards formula injection including leading spaces and full-width characters - Indian-script names print through the browser print path - Disabled reasons written on the page --- # Saving and sync > 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. Source: https://kwark.space/designSystem/patterns/saving-and-sync ## The problem A writer's first fear is losing words. It is not abstract at Kwark: in September 2026 a phone opening a light project card saved its placeholder over ten real pages of a screenplay. The founder made data loss priority one. At the same time, the writer is often on a train or a set with bad signal, and the same project is open on a laptop and a phone. They need three things: the work is saved without thinking about it, it is never overwritten by another device, and they can tell, at a glance and in words, where it is. ## Kwark's answer ### Save as you write, on the device first Every change is written to the device at once and queued for the cloud. The queue runs in order and keeps a change until the cloud confirms it; a failed upload backs off and retries (up to every five minutes) and is never dropped after an arbitrary number of tries. A change a person had no right to make (view-only access) stays on their device and is not reported as a failure, because it was never theirs to save. ### Cmd+S says Saved (Decision 0014) Writers press Cmd+S out of habit. It used to make a snapshot each time, which cluttered history and reassured nobody. Now Cmd+S (Ctrl+S) shows **"Saved. Your script saves as you write."** A deliberate restore point is **Keep a restore point**, Shift+Cmd+S, in the File menu. ### Revision stamps and conflict protection Every screenplay save carries a stamp: a revision number, the time, the device and the session. Two checks use it. - **On the device**, a save refuses to replace a newer revision written by another session. - **In the cloud**, the screenplay is written inside a transaction that compares revisions. If the cloud is newer, the upload stops, this device's version goes to the recovery store, the cloud copy is adopted, and the editor shows the conflict banner. A project whose screenplay has not reached this device (cloud unreachable, nothing local) opens read-only and never saves, so a blank cannot overwrite the real script. The honest limit, recorded in the memory note on conflict protection: a device still running an older app writes without a stamp and can still overwrite. The protection is in the app, not in the rules. ### One word, in the corner (Decision 0013) The state is told first, calmly, and only when it is worth telling. | State | Words | Colour | Shown | |---|---|---|---| | Loading | Loading… | Quiet | While opening | | Up to date | Up to date | Quiet | Briefly, then steps back | | Edited | Edited | Quiet | While typing | | Saving | Saving… | Quiet | During upload | | Saved | Saved | Ok | Briefly (about 2.6 seconds), then steps back | | Offline | Saved on this device | Warn, with the word | Until the cloud has it | | Not downloaded | Not downloaded, and a banner | Warn | Until it downloads; the page is read-only | | Conflict | Changed elsewhere, and a banner | Danger | Until the writer chooses | | Failed | Not saved | Danger | Until it saves | Outside the editor the account panel says **Safe**, **Safe here, waiting to reach the cloud**, or **Safe on this device (offline by choice)**, with **Retry**, **Backup** and **Work offline** or **Reconnect**. On Home, a story still only on the device carries **Not synced yet** (or **Only on this device** for a guest). Characters and locations say **Saved on this device** after a local write, which makes no cloud claim. ## Anatomy | Part | Means | The person does | |---|---|---| | Sync word | Where the work is now | Nothing, usually | | Conflict banner | Two sessions changed the screenplay | Chooses **Load the newer version** or **Keep mine** | | Not downloaded banner | The script is not on this device; nothing will save | **Try again** | | Recovery banner | Unsaved edits from an earlier visit were found | **Restore them** or **Discard** | | Cmd+S toast | Reassurance; nothing new happened | Keeps writing | ## Rules - **Must** write to the device before the cloud, and keep every queued change until the cloud confirms it. - **Must** stamp screenplay saves with a revision and refuse to replace a newer one. - **Must** open a project read-only when its screenplay has not reached the device. - **Must** keep the writer's version whenever two copies disagree. Loading the newer one saves theirs as a restore point first. - **Never** say "failed", "sync error" or raw Firebase text. Say the state and that the work is safe. - **Never** show a permanent bar for ordinary saving. "Saving 1 change" is the normal state of a writing app, not news. - **Never** carry the state by colour alone; every state has its word. - **Always** let Cmd+S answer "Saved". Never make it create a snapshot. - **Always** offer a way to take the work away when the cloud cannot be reached (Backup). ## Phone and desktop The same states and words everywhere. On a phone the sync word sits where it cannot be covered by the floating button; banners span the width under the one-line header and their actions wrap below the sentence. On desktop the word sits at the corner of the page. On a phone, a failure is one line: what went wrong and how to fix it. ## Writing - "Saved. Your script saves as you write." - "Saved on this device · sign in to keep it everywhere" - "Working offline · changes stay on this device" - "This screenplay was changed in another session. Your edits are kept on this device and have not overwritten it. Loading the newer version saves yours as a snapshot first." - "This screenplay has not downloaded to this device. Nothing will be saved until it does, so the copy elsewhere stays exactly as it is." - "Could not save. Your words are kept on this device." ## Accessibility - The sync word is in a polite live region, so a screen reader hears "Saved on this device" without being interrupted. - Banners use `role="status"`; their actions are real buttons, reachable by Tab, in reading order after the sentence. - A state that settles away must not take focus or move the page. **Do:** **Saved on this device**, in amber with the word, and a Retry button in the account panel. **Don't:** A red cloud with a line through it and "Sync failed", or a pulsing dot with no label. **Do:** Cmd+S shows "Saved. Your script saves as you write." and nothing else changes. **Don't:** Cmd+S makes a new snapshot every time and fills the history. ## Demo ```html
This screenplay was changed in another session. Your edits are kept on this device and have not overwritten it. Loading the newer version saves yours as a snapshot first.
Unsaved edits from 16 Nov, 21:40 were found on this device.
Safe here, waiting to reach the cloud3 changes only on this device
Saved on this device ``` ## Related [Errors](https://kwark.space/designSystem/patterns/errors.md), [Collaboration](https://kwark.space/designSystem/patterns/collaboration.md), [Loading](https://kwark.space/designSystem/patterns/loading.md), [Banner](https://kwark.space/designSystem/components/banner.md), [Toast](https://kwark.space/designSystem/components/toast.md). ## AI readiness test **Task:** Add autosave to the budget, which today saves the whole record on a button. **Give the agent:** This page, Review and quality (free tier), the memory note on conflict protection. **Constraint:** No new rules deploy without the founder. **A reliable answer:** - Writes to the device first and queues for the cloud - Uses field-path writes, not a whole-record overwrite, and states reads and writes per edit - Protects against a second editor overwriting (a stamp or per-field writes) and keeps both copies on conflict - Uses the sync words from this page, with no "failed" --- # Search and filter > 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. Source: https://kwark.space/designSystem/patterns/search-and-filter ## The problem A director preparing the night shoot wants every exterior scene at night with Mira in it. A writer wants to rename "Dev" to "Devraj" everywhere except where "Dev" is inside another word. A producer with forty stories in her library wants the two short films she is still drafting. Search in a writing tool usually means typing an exact string. But people do not think "EXT." and "NIGHT" in capitals; they think "Mira, night, outside". And filters that hide themselves leave people believing their stories have disappeared: an empty list with a filter on looks exactly like an empty library. ## Kwark's answer ### Search the way you would say it The screenplay's search (`ScriptSearch.tsx`) takes a sentence, not a pattern. Its hint says: "Ask it the way you would say it. A character's name, a time of day, inside or out, or the kind of line." The example placeholder is "mira night exteriors". Character names, day or night, interior or exterior and element types (dialogue, action) are understood from the script's own structure; everything else is matched as text. Two plain switches refine it: **Whole word** ("Only whole words — 'art' not in 'party'") and **Match case** ("Match upper and lower case exactly"). **Replace with** and **Replace** sit underneath. Results are grouped by scene in script order, and text found before the first scene heading is labelled "Before the first scene". No result says: "Nothing in the script matches that." Find is in Edit (Find and replace, ⌘F). On a phone it is in the Menu sheet near the top. ### Rename is not find and replace Renaming a character is its own command, **Rename a character…** in Edit, because a character's name appears in cues, action, the cast list, the breakdown and the call sheet. One rename changes them all, consistently, and is undoable as one step. Find and replace is for text. ### Filters stay visible and clear in one step On Home the library is found, filtered and sorted in one place: - On desktop: **Find a story…** (search), **Filter by format** (All formats, Feature films, Short films, Series, Franchises), **Filter by status** (Any status, Draft, Pre-production, Shared), **Sort projects** (Last edited, Date created, Name) with its direction. - On a phone: one labelled control, **Filter and sort**, opens a sheet holding the search field, sort and direction, format, status and **Clear filters** (Decision 0021). When a filter is on, the control's name says so: "Filter and sort, on". A second band with the search field appears only while searching. - When nothing matches: "No stories found" / "Try a different title, format, or status." with **Clear filters**. The same rules apply to comment filters (open or resolved, whose comments, newest or oldest first) and to the breakdown's department filters. ### Find within a module Modules with many items have their own find, labelled with what it finds: the Outline's **Find a beat**, the screenplay's **Go to scene…** (⌘G) for jumping by number or heading. A series-wide find across every episode is on the later list, not built; do not promise it. ## Anatomy | Part | Means | |---|---| | Search field | `type="search"`, labelled with its scope: "Search the screenplay", "Search projects" | | Hint | How to ask, in one line | | Refine switches | Whole word, Match case: chips with `aria-pressed` | | Results | Grouped in the work's own order (scene order, not relevance), each with where it is | | Count | "12 in this screenplay", in quiet text | | Active filter indicator | The word "on" in the control's name, or a removable tag per filter | | Clear filters | One action that removes every filter | | No result | One sentence and, if filtered, Clear filters | ## Rules - **Must** label every search field with its scope. - **Must** keep active filters visible, and give one action that clears them all. - **Must** distinguish "nothing matches" from "nothing here": a filtered-empty list never shows the welcome empty state. - **Must** order results in the work's own order (scenes in script order, stories by the chosen sort), never by an unexplained relevance score. - **Never** hide filters in a scrolling chip row with no cue (rejected in Decision 0021). - **Never** search more than the person can see. Results respect access: a Reader's search never returns a module they cannot open. - **Never** replace across the script without showing what will change; Replace works one at a time or shows the count before replacing all. - **Always** keep the query and filters when the person opens a result and comes back. - **Always** make search work for Indian scripts: match the text as typed, never transliterate the query silently. ## Edge cases - **Romanised query, Tamil script.** A writer types "meera" and the character is written in Tamil: match the cast name, which Kwark knows, not the characters on the page. - **A query that is a scene number.** "12" offers Scene 12 first. - **Very large scripts.** Search runs on the device, in the loaded script, with no cloud reads. - **Filter by a status nobody uses.** Offer only statuses that exist in the library, plus Any status. - **Shared with you.** The Shared tab has its own filters; the count shows only on the selected tab. ## Phone and desktop On desktop, search and filters sit in the toolbar above the list, each a labelled control; screenplay search opens in the side panel beside the page. On a phone, Home's find, filter and sort is one labelled icon in the single bar, opening a sheet; screenplay search opens from the Menu sheet as a full-height sheet whose results scroll the page to each match. ## Writing - Field labels: "Search the screenplay", "Search projects", "Find a story…", "Find a beat". - Hints say how to ask, once. - No result: "Nothing in the script matches that." / "No stories found". - Clear: **Clear filters**, **Clear search**. ## Accessibility - Search fields use `type="search"` with a visible label; the clear button is named "Clear search". - The result count is announced politely as it changes. - Refine chips are toggle buttons with `aria-pressed` and their full meaning in the accessible description. - The filter sheet returns focus to the Filter and sort control; its name includes "on" when filters are active. **Do:** "Ask it the way you would say it." and the example "mira night exteriors". **Don't:** A search box that needs "EXT." and "NIGHT" typed exactly, with a regex option as the only power. **Do:** "No stories found. Try a different title, format, or status." **Clear filters**, with "Filter and sort, on" in the toolbar. **Don't:** An empty library and no sign that the Short films filter is still on. ## Demo ```html
Short films

No stories found

Try a different title, format, or status.

Filter and sort
``` ## Related [Search field](https://kwark.space/designSystem/components/search-field.md), [Removable tag](https://kwark.space/designSystem/components/removable-tag.md), [Chip](https://kwark.space/designSystem/components/chip.md), [Sheet](https://kwark.space/designSystem/components/sheet.md), [Empty states](https://kwark.space/designSystem/patterns/empty-states.md), [Phones](https://kwark.space/designSystem/patterns/phones.md). ## AI readiness test **Task:** Add search and filters to the Breakdown's element list. **Give the agent:** This page, Decision 0021, Empty states. **Constraint:** On the device; no cloud reads per keystroke. **A reliable answer:** - Labels the field "Search the breakdown" and filters by department with visible removable tags - Results in scene order with the scene shown - Clear filters in one step - filtered-empty is not the welcome empty state - Phone folds it into one labelled Filter and sort sheet --- # Settings > 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. Source: https://kwark.space/designSystem/patterns/settings ## The problem A writer switching to Kwark from a decade in professional screenwriting software looks for the settings first: page size, what Return does after a character cue, whether names are suggested. In September 2026 she would not have found them. Choices were scattered as checkboxes inside menus under headings like "How the page reads". The founder called that "a lazy way to hand out options" and asked where the settings were. There is a second problem. A writer who is nervous should not open a new project to find it already counting, timing and outlining her. A setting's default is a claim about the person (the audit's lesson: "Defaults are claims"). A rhythm ring on Home, a stopwatch on the project page, a story stamped "Research" on creation: each told the writer something about herself she had not chosen. ## Kwark's answer ### One Settings window The screenplay's **Settings…** (⌘, in File) opens one window (`components/modals/SettingsModal.tsx`) with six sections: | Section | Holds | |---|---| | Appearance | Room, character colours, writing insights, timeline | | Page | Paper, and what the page shows | | Format & elements | For each element: after it, what Return makes; on it, what Tab turns it into | | Writing | Suggest names, Suggest extensions, Finish transitions, Enter on an empty line changes it, Check spelling, writing mode and languages | | Structure & production | Map the outline onto the script, What the page shows (the outline level), Pre-production on the page, Coverage help in the shot list | | Keyboard | The element digits, which the writer can reassign | Help › **Keyboard shortcuts** (⌘/) opens the same window at Keyboard. ### Every row says what it does and where it applies Each row is a title, one line of detail, the control, and a scope tag: - **All your scripts**: kept on this device for every script ("Suggest names", "Paper"). - **This project**: kept with the project, so collaborators see the same ("Character colours", "Timeline", "Map the outline onto the script"). Real rows: - **Paper**: "The page count, where pages break, the schedule's eighths and the PDF all follow it. A4 holds 60 lines, US Letter 55." - **Character colours** (This project): "Each voice in its colour — the one it has in the cast list, the breakdown and the shot list." - **Writing insights** (This project): "The character's card beside a cue, and the markers on a speech that open what it is doing." - **Timeline** (This project): "The film's running time above the page, scene by scene." - **Suggest names**: "Characters offered as a cue is typed, from the cast and the script." - **Suggest extensions**: "After "(": the ones this script uses first, then V.O., O.S., CONT'D and the rest." - **Finish transitions**: "The rest of a transition shown faint as it is typed; Tab takes it." - **Enter on an empty line changes it**: "An empty speech becomes action; an empty parenthetical, dialogue — instead of leaving a blank line." - **Check spelling**: "The browser's own spelling check, underlined on the page." - **Pre-production on the page** (This project): "Breakdown, shot list and schedule as tabs beside Screenplay, worked on the script itself." ### Changes apply at once There is no Save or Apply. A switch takes effect on the page behind the window as it is changed, and is kept. A digit reassigned in Keyboard works the moment it is chosen. ### Optional things start off - **Writing rhythm** is off by default for everyone, out of Home, kept in Settings as a private, quiet option: no flame, no streak, no resets (Decision 0008). - **Structure features** default to off for a script with no linked outline; when the beat map is off, only its switch shows (Decision 0003). - **Writing insights** are off by default and say so. - New projects start empty: no stamped status, no pre-filled outline. ### Outside the screenplay Project-wide choices live in **Project settings**, from the project's menu. The model row: **When I open a project**, with **Project home** (default) and **Where I left off**, each with a one-line meaning (Decision 0018). It is kept per person on this device today. Account choices (display name, picture, sign out, work offline) live in the account panel. ## Anatomy | Part | Rule | |---|---| | Section list | Left on desktop, a first page on a phone; plain nouns | | Row title | The feature's name, as in the menus | | Detail line | What it does or changes, in one sentence; may say "Off by default." | | Scope tag | "This project" or "All your scripts" | | Control | Switch for on or off; segmented or select for one of several; a table for per-element maps | | Disabled row | Dimmed with its reason in the detail line (for example, "What the page shows" needs the outline mapped first) | ## Rules - **Must** put every kept choice in Settings, not in a menu as a checkbox. - **Must** give every row one line that says what it changes, and its scope. - **Must** apply changes at once; no Save or Apply buttons. - **Must** default optional, structure-aware and self-measuring features to off. - **Must** make every switch turn its feature fully off; a switch that leaves part of it behind is a bug (Decision 0003). - **Never** add a setting that does not change something a person can see. - **Never** use a setting to hide a design decision Kwark should make. If nearly everyone picks one option, make it the only behaviour (Decision 0018's removal test). - **Never** default to anything that counts, times or grades the writer. - **Always** use the same name in Settings as in the menu that shows the feature. - **Always** show a disabled row's reason in words. ## Edge cases - **A collaborator changes a This-project setting.** It changes for everyone; the row's scope tag says so before they change it. - **Read-only person.** Project rows show their state, disabled, with "Only people who can edit this project can change this." - **Two digits for one element.** The later choice wins and the earlier element loses that digit; the Keyboard table shows the result at once. - **A setting not saved to the account yet.** Say where it is kept ("on this device") rather than implying it follows the person. - **Country-specific choices** (tax, paperwork) are settings with the country named, never a fixed assumption. ## Phone and desktop On desktop Settings is a dialog with the section list on the left and rows on the right, closed with Escape or **Close settings**. On a phone it is a full-screen sheet: the first page lists the sections, each opens its own page with a labelled back row, and rows are 44px with the control on the right. ## Writing - Titles are the feature: "Suggest names", not "Enable name suggestions". - Detail lines describe the effect, never the benefit: "The film's running time above the page, scene by scene." - Scope: exactly "This project" or "All your scripts". ## Accessibility - The window is a dialog labelled "Settings"; the section list is a navigation landmark labelled "Settings sections". - Each switch's accessible name is the row title; the detail line is its description. - Per-element selects carry full names: "After Character, Return makes". - Changing a setting never moves focus. **Do:** **Timeline** (This project): "The film's running time above the page, scene by scene." Off until turned on. **Don't:** A "How the page reads" heading in the View menu with six unexplained checkboxes. **Do:** Writing rhythm off by default, in Settings, with no flame and no streak. **Don't:** A rhythm ring on Home for every new account, counting days since the last session. ## Demo ```html
Structure & production
Map the outline onto the script This project
The outline's acts and beats, landed on the scenes they belong to.
What the page shows This project
Map the outline onto the script first.
Pre-production on the page This project
Breakdown, shot list and schedule as tabs beside Screenplay, worked on the script itself.
Paper The page count, where pages break, the schedule's eighths and the PDF all follow it. A4 holds 60 lines, US Letter 55.
``` ## Related [Switch](https://kwark.space/designSystem/components/switch.md), [Segmented control](https://kwark.space/designSystem/components/segmented-control.md), [Select](https://kwark.space/designSystem/components/select.md), [Dialog](https://kwark.space/designSystem/components/dialog.md), [Menus and shortcuts](https://kwark.space/designSystem/patterns/menus-and-shortcuts.md), [Structure, not teaching](https://kwark.space/designSystem/method/structure-not-teaching.md). ## AI readiness test **Task:** Add a setting for showing scene runtimes in the scene list. **Give the agent:** This page, Decision 0003, Decision 0008, Menus and shortcuts. **Constraint:** Only if it changes something visible. **A reliable answer:** - Puts it in Settings › Appearance (or View if it is a live toggle), not as a menu checkbox - Row has a title, a one-line detail of the effect and a scope tag (This project) - Applies at once with no Save - Defaults off unless the founder decides otherwise, and turns fully off --- # Sharing and roles > 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. Source: https://kwark.space/designSystem/patterns/sharing-and-roles ## The problem A writer has finished a draft and wants her director, two actors and a DOP to read it before the table read on Saturday. Before November 2026, Kwark asked her to choose three tabs, a "how they get in" option before she could even type an address, and then 14 modules × 4 levels: 56 buttons in a nested scroll. The default was **edit everything**. Nobody she invited was ever told, because Kwark sends no email. A person she removed was told the project had been deleted. A declined request could never be asked again. A locked module told collaborators it was "still being built". Her screenplay is the most sensitive thing in Kwark. If sharing is confusing she either does not collaborate, or she over-shares by accident. The founder: "the sharing module UX and UI both are very very bad… we are not providing a good user experience to the people who would want to collaborate… not just fix the UI, better user experience, ease of use, and more usefulness." ## Kwark's answer Decision 0042: sharing by film role, in one panel, safe by default. ### One panel, in the order of what matters 1. **Requests first** (someone is waiting): "Asking to join", with **Keep** and **Decline**. Appears only when someone is waiting. 2. **Add people**: email addresses, a role, and an optional end date. 3. **Who has access**: everyone, each with their role and a ⋯ menu. 4. **The request link**, off until turned on. ### Roles a producer would name A role is a template over the per-module map; the map is the authority, and access is never trusted to the label. Roles that behave the same in this copy of the app are not offered twice. | Role | What it gives | |---|---| | Reader | Reads the screenplay. Nothing else. | | Actor | Reads the screenplay and characters, and sees the calendar. | | Co-writer | Writes with you: screenplay, outline, characters, world, research, pitch. | | Director | Edits the screenplay, story and production. Reads the pitch. | | Producer | Runs production: cast and crew, calendar and pitch. Reads the story. | | Camera | Shapes the look and the shots. Reads the screenplay and production office. | | Crew | Reads the screenplay, production pages and the calendar. | | Custom | Any module-by-module change turns the label into Custom. | Underneath, **Module by module…** gives the fine-tune: each module is **No access**, **Can read** or **Can edit**. Screenplay covers every draft and episode; Research keeps personal notes private; Cast and crew includes contact details; Production office is one permission today (breakdown, shots, schedule, call sheets, budget, paperwork, departments), and splitting it so an actor can see call sheets without the budget is the first follow-up. ### Safe defaults - New people are **Readers**. - The request link is **off**. When on, it offers a role and every person who asks is approved by the owner: "The link is on. You approve everyone who asks." / "The link is off. Nobody can ask through it." - Sharing works through Google accounts, so only the people you add can open it. ### Kwark sends no email, so it says so After inviting, the panel offers **Copy invite message** and **Email the invite** (the owner's own mail app). The message: > {Owner} has shared "{title}" with you on Kwark, as {Role}. Open it here: {link}. Sign in with the Google account for {email}. Kwark only lets that address in. Copying says "Copied. Paste it into WhatsApp or an email." Invites point to `/invited/{project}`, which tells the person which Google account to use and who invited them, as what, before they sign in. ### Per person (⋯) Module by module…, Set an end date…, Parts they read…, Draft they see…, Named on project page, Copy invite message, Email the invite, and **Remove access** (confirmed). "Draft they see" is a view preference, not a security boundary, and the panel says so. ### On the collaborator's side - Permission changes arrive live. - A module not shared with them: "{Owner} hasn't shared {module} with you." / "Ask {Owner} if you need it." Locked and hidden merged into one **No access**; neither was readable, and a lock tile only invited a question nobody could answer. - When access ends, a named page: "Your access has ended", "Your access to {project} ended on {date}.", "You left this project", with **Go to your projects**. Never "the project has been deleted". - **Leave project** is always available to them. ## Anatomy | Element | Means | |---|---| | Requests box (accent outline) | People waiting; the count is how many | | Role button (word and chevron) | Opens the role menu; the word is the current role | | Dashed envelope avatar | Invited, has not signed in yet ("Invited · not joined yet") | | "Until 30 Dec" | Access ends after that day | | "Access ended …" | Dims the row | | Request link Off or On | Whether anyone with the link may ask to join | | Bell bubble number (accent) | People asking to join, across your projects; it never pulses | ## Rules - **Must** default new people to Reader and the request link to off. - **Must** check access against the per-module map, never the role label. - **Must** say plainly that Kwark sends no email, and give Copy invite message and Email the invite. - **Must** name every person with access and make each removable, with a confirm that says what they keep. - **Must** show a collaborator a named "access ended" page and a calm "hasn't shared" page, never a deletion message or "still being built". - **Never** let anyone in by link alone; the owner approves every request. - **Never** offer a role that behaves the same as another in this copy of the app. - **Never** let a collaborator create edit access for another account. (The old rules allowed it; the rewritten rules on `feat/sharing-rebuild` close it and are not deployed without the founder.) - **Always** put waiting requests first. - **Always** make one change one batch, and say so if it fails: "That change was not saved. Try again." A failure must never look like "nobody has access". ## Edge cases - **The owner types their own address:** "That is your own address. You already own this project." - **A date in the past:** "Choose a date after today, or choose No end date." - **Wrong Google account at the invite:** the join page names the address the invite was for. - **Declined request:** the person may ask again later; a decline is not permanent. - **A new link:** **Make a new link?** retires the old one; "A new link is ready." - **Browser blocks copying:** "Your browser blocked copying. Select the text and copy it yourself." - **Not signed in:** the panel shows **Sign in to share** and why: sharing works through Google accounts. ## Phone and desktop On a phone the panel is full screen with the one-line header ("Share") and one scroll; each person's ⋯ opens a sheet that drills into Module by module one page at a time. On desktop it is a single dialog with one scroll, never nested scroll areas. Every control is a word, reachable by keyboard. ## Accessibility - The role button's accessible name includes the person: "Dev Rao's role: Director". - The requests box is a region with a heading and a count in words. - Module levels are a radio group per module with a legend naming the module. - The dashed envelope avatar has a text equivalent: "Invited, not joined yet". **Do:** Add "dev@example.com" as **Reader** (the default), then **Copy invite message** and paste it into WhatsApp. **Don't:** Add "dev@example.com" with edit access to every module by default and show "Invitation sent" when nothing was sent. **Do:** "Mira hasn't shared Budget with you. Ask Mira if you need it." **Don't:** A lock icon and "This module is still being built." ## Demo ```html
Asking to join
AKAsha Kumar
asha@example.com · asks as Actor
Add people
Kwark doesn't send emails. Let them know, and say which Google account to use.
``` ## Related [Avatar](https://kwark.space/designSystem/components/avatar.md), [Menu](https://kwark.space/designSystem/components/menu.md), [Copy field](https://kwark.space/designSystem/components/copy-field.md), [Destructive actions](https://kwark.space/designSystem/patterns/destructive-actions.md), [Collaboration](https://kwark.space/designSystem/patterns/collaboration.md), [Notifications](https://kwark.space/designSystem/patterns/notifications.md). ## AI readiness test **Task:** Let an actor see call sheets without seeing the budget. **Give the agent:** This page, Decision 0042, utils/shareRoles.ts, never-test-rules-on-live-project. **Constraint:** No rules deploy without the founder. **A reliable answer:** - Splits the Production office permission in the module map, not in the role label - Updates the Actor template to read call sheets only - Makes production pages cope with partial data - Plans rules in the emulator and asks before deploying - The collaborator sees "hasn't shared Budget with you" for the rest --- # 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 --- # Releases > What is in each version of the Kwark Design System, what changed, what is known to be missing, and what comes next. Source: https://kwark.space/designSystem/releases ## v4.0 · 16 November 2026 Version 4 rebuilds the system from the app outwards. Every component was taken from Kwark's source and reproduced in `kw-` CSS with the app's geometry, type, colours, states and words. Every rule cites the decision it comes from. ### What is in it - **One source, two readers.** Every page is written once in `design-system/content/` and built twice: an HTML page for people and a markdown twin for agents (the same URL plus `.md`). Each page has a Person and Agent switch. - **Foundations.** Colour roles with light, dark and five writing rooms; type, space, radius, elevation, layout, motion, icons; principles, accessibility, inclusive design, writing systems, content, UX writing, AI and authorship, data visualisation. - **Components**, grouped by job (actions, inputs, selection, navigation, feedback, overlays, layout, data display, data visualisation, media, creative tools, AI and authorship, collaboration). Each has usage, style, code, accessibility and agent rules, and a status label: In the app, Ready for Kwark or New. - **Patterns** for creative tools, **Creative app kits** for screenwriting, editing, storyboards, scheduling, sound, grading and production offices, and the **Kwark method**. - **kwark.css**: every token and the framework-free component styles in one file. - **For agents**: `llms.txt`, `llms-full.txt`, `AGENTS.md`, `tokens.json` (DTCG 2025.10 token manifest), `components.json` and `search.json`, all generated on each build. - **An MCP server** (`kwark-design-mcp.mjs`, no dependencies) with five tools: `search_docs`, `get_page`, `get_component`, `get_tokens` and `audit_code`. See [MCP server](https://kwark.space/designSystem/agents/mcp.md). - **Skills** to download: six for building (kwark-ui, kwark-ux-review, kwark-ux-copy, kwark-handoff, kwark-decision-record, kwark-creative-app) and eight for the product method (kwark-frame-problem, kwark-synthesise-research, kwark-map-opportunities, kwark-test-assumptions, kwark-prioritise, kwark-write-spec, kwark-measure-outcome, kwark-check-release). See [Skills](https://kwark.space/designSystem/agents/skills.md). - **A handoff template** and a [prompt library](https://kwark.space/designSystem/agents/prompts.md). - **An AI readiness test** on every foundation, pattern, kit and component page, and a [roadmap](https://kwark.space/designSystem/agents/roadmap.md) for teams adopting the system. ### What changed from v3 - **The site is static.** Version 3 was a portal inside the app (`pages/Design`, Decision 0045). Version 4 is generated into `public/designSystem/` by `node design-system/build.mjs` and needs no app code to run. - **The look was redone.** Version 3 was rejected as generic: decorative illustrations, an accent picker, terracotta, monospace labels, cards and breadcrumbs that could have belonged to any product. Version 4 shows only parts as Kwark draws them. - **The MCP tools were renamed.** `kwark_docs_search`, `kwark_tokens_lookup`, `kwark_component_spec`, `kwark_code_audit` and `kwark_dataviz_spec` became `search_docs`, `get_page`, `get_component`, `get_tokens` and `audit_code`. `get_page` is new and returns any page as markdown. The data-visualisation recipe now lives on its foundation page. Update any saved prompts that name the old tools. - **`rules.md` is now `AGENTS.md`.** The name is the one coding agents look for. - **Tokens are read from `kwark.css`**, not from the app's `styles/tokens.css`. The `--k-*` names are unchanged. ### Known gaps Said plainly, so nobody builds on an assumption. - **No Figma library.** It is planned. Until then, the live pages are the visual reference. - **No published React package.** The React components are in the Kwark app's `components/ui/`. Outside Kwark, use `kwark.css` and the `kw-` HTML. - **`kwark.css` does not load fonts.** Load Poppins, Raleway and Courier Prime yourself. - **The app's light theme is unfinished.** Kwark opens in dark. The light values here are specified, but not every app screen uses them yet. - **`audit_code` is a heuristic.** It reads lines, not a syntax tree. A clean result is not a review. ## Earlier versions - **v3.0, 15 November 2026.** The in-app portal at `/designSystem` with the first MCP server and machine-readable files (Decision 0045). Replaced by v4. - **Before v3.** The system was a one-page rules file (`docs/design-system.md`), the token file and a small specimen sheet at `/design`. The rules file is still the short summary the tests enforce. ## What is next These are plans, not dates. Each will be in a release note when it lands. - **Figma library**, built from `tokens.json` so the values match. - **React components for every Ready for Kwark part**, added to `components/ui/` as Kwark needs them, each with its page updated in the same change. - **A readiness index** generated by the build, so [Readiness tests](https://kwark.space/designSystem/agents/readiness.md) lists every component test automatically. - **Guides**, see [Guides](https://kwark.space/designSystem/guides.md). ## AI readiness test **Task:** A team on v3 asks what they must change in their agent setup to use v4. **Give the agent:** This page, MCP server, AI context files. **Constraint:** Only changes listed here. No invented migration steps. **A reliable answer:** - Renames the five MCP tools correctly - Says rules.md is now AGENTS.md - Says token names are unchanged - Mentions get_page as new - Notes that there is no Figma library or React package --- # What sets Kwark apart > Ten things this system does that a general-purpose design system does not, most of them not about how the interface looks. Each one links to the rule, the decision or the file that proves it. Source: https://kwark.space/designSystem/what-sets-kwark-apart Most design systems describe how an interface looks. Kwark's also says who may change a writer's words, which decision a rule comes from, what an agent must prove before its code ships, and how a page prints on paper for a crew at 6 a.m. These ten points are the reasons to choose it. Each one is a rule written into the system or a file you can download today, not a promise. ## 1. Authorship is a rule, not a setting A machine in Kwark may find, move, convert or carry the writer's own words. It never writes them, scores them or judges them (Decision 0002). That one sentence decides how every AI feature is built: proposals come from the writer's own outline beat or script, carry a revision mark until the writer accepts or rewrites them, and record where they came from. General systems give you a "sparkle" button style. This one gives you the line a feature may not cross, and a test that fails when it does. See [AI and authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md), [Revision mark](https://kwark.space/designSystem/components/revision-mark.md) and [AI assistance pattern](https://kwark.space/designSystem/patterns/ai-assistance.md). ## 2. Every rule traces to a decision Rules are not opinions. Each one points to a numbered decision record with the problem, the options, the choice and the date: the phone header (0016), call sheet revisions (0020), sharing by film role (0042), the breadcrumb (0044). When a rule is wrong, you change the decision and the rule follows, and you can see why it was made in the first place. See [Decision records](https://kwark.space/designSystem/method/decision-records.md). ## 3. Written once, read by people and by agents Every page is published twice: as a page for people and as clean markdown for agents, from the same source. The system ships `AGENTS.md`, `llms.txt`, W3C design tokens, an MCP server that can audit code against the rules, and fourteen skills. Flip any page to Agent and you see exactly what a coding agent receives. See [For agents](https://kwark.space/designSystem/agents/index.md), [MCP server](https://kwark.space/designSystem/agents/mcp.md) and [Skills](https://kwark.space/designSystem/agents/skills.md). ## 4. Agents have to pass a test Every foundation, pattern and kit ends with a readiness test: a task, the context the agent gets, a constraint, and the behaviours that count as reliable. You run it against your own agent and see whether it follows the system before you trust its output. The tests are part of the documentation, not a separate QA project. See [Readiness tests](https://kwark.space/designSystem/agents/readiness.md) and [AI-ready roadmap](https://kwark.space/designSystem/agents/roadmap.md). ## 5. Built for the work, not the dashboard Generic systems stop at buttons, forms and tables. Kwark carries on into the parts of a film: the screenplay page with print geometry, index cards, the stripboard, the call sheet with numbered revisions, the shooting calendar, the cast board, storyboards, and kits for editing, colour grading and sound. Teams building any creative tool start from the hard parts instead of drawing them from scratch. See [Creative app kits](https://kwark.space/designSystem/kits.md) and [Components](https://kwark.space/designSystem/components.md). ## 6. Paper and digital in one act A crew still works from paper. Every structured artefact in Kwark has a printed form that matches the industry's: the screenplay page at the right margins, the call sheet a first AD would recognise, revision colours in the standard order. The screen and the page are designed together, so nothing has to be re-typed into a spreadsheet to be printed. See [Print and export](https://kwark.space/designSystem/patterns/print-and-export.md) and [Screenplay page](https://kwark.space/designSystem/components/screenplay-page.md). ## 7. Every script, on the same page Screenplays in India, and in most of the world, mix languages. The system has a font token per script, phonetic typing on an English keyboard, right-to-left lines, and rules for numbers, case and sorting across scripts, so Devanagari, Tamil and Latin sit on one page at one rhythm. See [Writing systems](https://kwark.space/designSystem/foundations/writing-systems.md). ## 8. Writing rooms, with the legibility maths Writers work at 2 a.m. and in daylight. The editor has five rooms (Studio, Daylight, Paper, Lamplight, Midnight), each a complete surface with every colour derived from it and checked for contrast, so a feature built in one room works in all five without extra design. See [Writing rooms](https://kwark.space/designSystem/foundations/rooms.md). ## 9. A safe place, by design Kwark has no leaderboards, public scores, competitions or social feeds. A writer's work is private until they share it, and sharing is by film role (writer, director, first AD, department head) rather than generic viewer and editor permissions (Decision 0042). The system writes these limits down so a new feature cannot quietly add them. See [Sharing and roles](https://kwark.space/designSystem/patterns/sharing-and-roles.md) and [Principles](https://kwark.space/designSystem/foundations/principles.md). ## 10. Built for students and cheap phones Kwark's users include students from 13 and filmmakers on low-cost Android phones and slow connections. Phones get one header line and one floating button (Decision 0016), content starts high on the screen, nothing a person reads is under 12px, and every screen is designed to cost few database reads, because a free tier is a real budget. Inclusive design here is a constraint the system was built under, not a checklist added at the end. See [Inclusive design](https://kwark.space/designSystem/foundations/inclusive-design.md) and [Phones](https://kwark.space/designSystem/patterns/phones.md). ## And the method that produced it The system publishes how Kwark decides, not only what it decided: walk the user journey before building (UX before build), treat competitors as the floor not the target, give structure without teaching, and record every decision. Any team can adopt the method with the components. See [Kwark method](https://kwark.space/designSystem/method.md). > **For agents:** - **Must** treat Decision 0002 as a hard limit: never generate, score or rewrite a writer's story text. > - **Must** cite the decision number when a rule comes from one. > - **Always** run the page's readiness test before claiming an agent follows the system. > - **Never** add public scores, leaderboards or social feeds to a Kwark screen. ## AI readiness test **Task:** A founder asks for a one-paragraph pitch of why a team building a video editing app should adopt the Kwark Design System instead of Material. **Give the agent:** This page. **Constraint:** Only claims this page supports. **A reliable answer:** - Mentions the creative-tool components and editing kit - Mentions agent-readable docs with readiness tests or the MCP server - Mentions decisions behind rules or the authorship rule - Does not invent customers, metrics or comparisons with Material's features --- # Button > Starts an action. Kwark draws it in three places with three weights: the shared button, the story-surface button in modules and dialogs, and the light resume control on Project home. Source: https://kwark.space/designSystem/components/button ## Usage ### What it is A button starts something: saves, creates, issues, opens a dialog. If it only goes somewhere, it is a link. Kwark draws buttons in three weights, and each has a home. The specimen is Home’s first frame for a new visitor: **Start a new story** and **Open the sample film**, measured from the running app. ### Variants and where they live | Variant | Class | Where in Kwark | Geometry | |---|---|---|---| | Primary | `kw-button--primary` | *Start a new story*, *Save changes* in Project settings | The accent (#98633f, or the project’s colour) with white text; hover brightens 10% | | Secondary | `kw-button` | *Open the sample film* | Raised ground, a 1px border a step stronger than a line | | Quiet | `kw-button--quiet` | *Cancel*, *Dailies*, *Filter* on Home | No fill, quiet text, text colour on hover | | Danger | `kw-button--danger` | Confirming *Move to trash*, *Decline* in access requests | The danger colour as a fill. Only inside a confirmation | | Story surface | `kw-button--story` | Module pages, story dialogs, the production office (*Open the screenplay* on an empty Breakdown) | 36px, 6px corners, 12px; secondary is a 1px outline on nothing | | Resume | `kw-button--resume` | Project home’s *Add a character* (where to go on) | The text colour as a fill, a trailing ↗, 44px, as wide as its column | Home’s blue **New project** is a fourth, single-use button: see [Top bar](https://kwark.space/designSystem/components/top-bar.md). Never use it inside a project. ### Sizes 28px (`--sm`, inside panels and toasts), 36px by default, 44px (`--lg`) where it is the main action of a screen and everywhere under a thumb. On a phone every button grows to 44px. ### Writing the label - A verb and its object, in sentence case: **Save changes**, **Move to trash**, **Open the screenplay**. Never *Submit*, *OK* or *Yes, do it*. - The same word through the flow: the button says *Move to trash*, the toast says *Project moved to trash*. - A chevron only when it opens a choice (*New project ▾*); a ↗ only on the resume control. ### Moving older code over `Button.tsx` still renders the old `ds-btn` (upper case, 0.05em tracking, 10px at the small size). Every visible use adds `k-btn-plain` for sentence case. Use the shared `Button` with `className="k-btn-plain"` until the base class is changed. **Do:** One primary, named for what happens: **Issue call sheet**. *Cancel* beside it is quiet. **Don't:** Two primaries side by side, or an upper-case **EXECUTE ACTION** that makes the reader guess. ## Style ### Anatomy 1. **Container**: 8px corners (`.ds-btn`); the story-surface and resume variants use 6px (`--k-radius-control`). 2. **Heights**: 28 · 36 · 44px. Padding 10 · 14 · 18px. 3. **Label**: Poppins 500, 14px (12px in the story surface and at 28px). 4. **Icon**: 14px, leading, 8px gap. Trailing only for a chevron or the resume ↗. 5. **States**: hover brightens the primary by 10% and steps the secondary’s ground; disabled is 50% opacity with `cursor: not-allowed`; busy keeps the width and shows the 16px ring. 6. **Focus**: 2px ring in `--k-accent-soft`, 2px off the edge. ### Tokens | Token | Light | Dark | |---|---|---| | `--k-accent` | #98633f | #98633f | | `--k-on-accent` | #ffffff | #ffffff | | `--k-raise` | #f1f5f9 | #252525 | | `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) | | `--k-text` | #0f172a | #e3e3e3 | | `--k-text-2` | #5b6779 | #9ca3af | | `--k-danger` | #b4382c | #e0685c | | `--k-bg` | #f8fafc | #191919 | | `--k-accent-soft` | #e8b58b | #e8b58b | | `--k-radius-control` | 6px | | | `--k-control-md` | 36px | | | `--k-tap` | 44px | | | `--k-fs-body` | 14px | | | `--k-fs-meta` | 12px | | ## Code ### React In the Kwark app: `import Button from '@/components/ui/Button'`. ```tsx ``` | Prop | Type | Notes | |---|---|---| | `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'danger'` | `ghost` is the quiet button | | `size` | `'sm' \| 'md' \| 'lg'` | 32, 36, 44 px | | `icon` | `LucideIcon` | leading icon | | `iconRight` | `LucideIcon` | trailing icon, e.g. a chevron | | `loading` | `boolean` | sets aria-busy and keeps the width | ### HTML and CSS Works anywhere with `kwark.css`. ```html
``` ## Accessibility ### Keyboard | Key | Does | |---|---| | Tab | Moves focus to the button. Focus shows a 2px ring in `--k-focus`, 2px off the edge. | | Enter / Space | Activates it. | ### Rules - Use a real `

On a draft the numbers simply follow on, and Omit waits until the script is locked.

``` ## Accessibility ### Keyboard | Key | Does | |---|---| | Tab | Reaches each member in order. A button group is not a toolbar; no arrow-key model. | | Enter / Space | Runs the focused command. | ### ARIA - `role="group"` and an `aria-label` that names the object. - When the visible label is short (*Add after*), the accessible name says all of it: *Add a scene after Scene 12, numbered 12A*. - An unavailable member uses `aria-disabled="true"` and stays focusable, so its reason (*A draft renumbers; Omit is for locked scripts*) can be read in a tooltip or hint. - The focused member's ring is drawn above its neighbours (`z-index: 2`) so it is never clipped. ## For agents ### Rules - **Must** keep every member acting on the same object, and name that object in the group's aria-label. - **Never** renumber scenes on a locked script: offer insert with the letter it will take (12A) and Omit, never delete. - **Must** keep one primary at most, and only in the spaced form. - **Always** stack a joined group into 44px full-width rows under 768px. - **Never** use a button group to pick a mode or view; that is a segmented control. ### AI readiness test **Task:** Add scene actions to the Outline card menu for a locked screenplay. **Give the agent:** This page, Breadcrumb for scope, revision.ts rules quoted here. **Constraint:** The script is on its Pink revision; Scene 46 is on tomorrow's call sheet. **A reliable answer:** - Insert after 46 shows "46A" - Omit Scene 46 instead of delete - No renumbering - aria-label names Scene 46 - Stacks on phones --- # Copy field > A link that leaves the room: the call sheet’s address, what revision it shows, who can open it, and one button that copies it and says so. Source: https://kwark.space/designSystem/components/copy-field ## Usage ### What it is A copy field shows a value someone will paste somewhere else, and copies it in one press. In Kwark that is usually a link that leaves the room, so the field says what the link opens before anyone sends it: **which revision** (*Rev 3*), **what it allows** (*View only*), and **who it reaches** (*Cast and crew of Blank Pages*). Sharing is by film role (Decision 0042), and a person should never paste a link without knowing who it lets in. ### When to use - A call sheet, a reading-cast invite, a review link for a cut; any address shared outside Kwark. - A short value people retype by mistake: a project code, a timecode for the editor. ### When not to - Sending directly to people Kwark already knows: use the share dialog, which names them. - Long text (a whole Fountain file): a [Code block](https://kwark.space/designSystem/components/code-block.md) with its own copy, or a download. ### Behaviour - **Copy link** puts the value on the clipboard, then says *Copied* with a tick in the success colour for 1.4s before returning. A polite status says the same in words. - If the browser refuses, the button reads *Select and copy*, the field selects its text, and the line under it says which keys to press. The value is never hidden behind a failure. - The field is read-only, focusable and selectable; clicking it selects all. - When the call sheet is revised, a link that keeps working says so (*Rev 4 will use the same link*). Issued revisions stay frozen (Decision 0020). **Do:** *Rev 3 · View only · Cast and crew of Blank Pages* under the link, and *Copied* after the press. **Don't:** A bare URL with a clipboard icon and no word of what it opens or who can open it. ## Style ### Anatomy 1. **Box**: 44px, 1px `--k-line`, 6px corners, no fill (it is read-only). 16px link glyph in `--k-text-2`. 2. **Value**: 14px tabular, ellipsised at the end; the whole value is selectable. 3. **Button**: inside the box on the right, 36px, 4px corners, `--k-raise` with a 1px line; 14px copy glyph and *Copy link* in 500 12px. Hover: `--k-line-strong` edge. 4. **Copied**: `--k-ok-bg` fill, `--k-ok` text, a 2px-stroke tick. 5. **Meta**: 12px `--k-text-2`, beginning with the revision tag (1px `--k-ok` box, as on the call sheet). 6. **Failed**: `--k-warn` edge on the box, the value highlighted as selected, the instruction in `--k-warn`. ### Tokens | Token | Light | Dark | |---|---|---| | `--k-surface` | #ffffff | #1a1a1a | | `--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-soft` | #e8b58b | #e8b58b | | `--k-ok` | #2c6e49 | #6cc08a | | `--k-ok-bg` | #e7f3ec | #17281e | | `--k-warn` | #8a5a00 | #d8a44a | | `--k-tap` | 44px | | | `--k-radius-control` | 6px | | ## 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
Call sheet link · Day 7

Rev 3View only · Cast and crew of Blank Pages · Rev 4 will use the same link

Call sheet link · Day 7

Link copied. Paste it into the unit’s group.

Call sheet link · Day 7

This browser blocked copying. The link is selected: press ⌘C or Ctrl+C.

``` ## Accessibility ### Keyboard | Key | Does | |---|---| | Tab | The value, then the button. | | Enter / Space on the button | Copies. | | ⌘C / Ctrl+C in the value | Copies what is selected. | ### Roles and names - The value is a read-only `` named with what it is and for: *Call sheet link for Day 7*. - The button keeps its label in words; when it changes to *Copied*, a polite `role="status"` line says *Link copied* so nothing depends on seeing the button. - Do not disable the button while it shows *Copied* in a way that drops focus; keep focus on it. - The revision and access line is plain text next to the field, read in order after the button. ## For agents ### Rules - **Must** say what a shared link opens and who it reaches, next to the link. - **Must** confirm a copy in words ("Copied") and in a polite status. - **Always** fall back to selecting the value with keyboard instructions when the clipboard is refused. - **Never** hide or truncate a value so that it cannot be selected and copied by hand. - **Always** label the copy button with its object: "Copy link", not "Copy". ### AI readiness test **Task:** Show the share link for the Day 7 call sheet after it is issued. **Give the agent:** Copy field, Call sheet, Decisions 0020 and 0042. **Constraint:** The link is view only for the cast and crew; Rev 3 is current. **A reliable answer:** - Read-only field named Call sheet link for Day 7 - Copy link button - Copied with a polite status - Rev 3, View only and who it reaches beside it - Fallback selects the text --- # Floating action button > One labelled action floating at the foot of a phone screen, for a surface that has no floating dial. It names where the new thing will land. Source: https://kwark.space/designSystem/components/floating-action ## Usage ### What it is A 48px pill that floats 16px from the bottom-right of a phone screen and does one thing: make the next item of what the screen lists. It exists for surfaces that do not show the [floating dial](https://kwark.space/designSystem/components/floating-dial.md), such as a standalone shot list opened from a link, or a tool built on the Kwark system outside the app. ### The one-floating-control rule Kwark phone screens have exactly one floating control (Decision 0011, Decision 0016). Where the dial is present, the dial is the floating control and *Add shot* goes into the page content or the Menu sheet. A floating action button never sits beside the dial. ### The Kwark idea: it says where the new thing lands A generic FAB is a plus. Kwark's names the item it will create, with the number it will take: **Add shot 12C** under Scene 12, **Add scene 47A** on a locked script, **Add day 25** in the schedule. People can see before they press that the shot goes into Scene 12, not wherever they were last week. Scrolling down shrinks it to the plus and the number (*+ 12C*); scrolling up brings the word back. ### When to use - One creation action that is the main reason for the screen, on a phone, where the screen has no dial. ### When not to use - On desktop: use a [button](https://kwark.space/designSystem/components/button.md) in the module head. - For navigation, saving, or anything destructive. - When the screen already has the dial, a sheet open, or the keyboard up (it tucks away while typing). ### Room for it The page keeps `--k-fab-slot` (78px plus the safe area) free at its foot, so the last row is never under the button. ## Style ### Anatomy 1. **Pill**: 48px tall, 14px left and 16px right padding, `--k-radius-pill`, `--k-accent` with `--k-on-accent` text, `--k-shadow-pop` (it floats). 2. **Glyph**: a 20px plus at stroke 2. 3. **Label**: verb and object, Poppins 500 14px: *Add shot*. 4. **Number tag**: 22px pill, 20% `--k-on-accent` wash, Poppins 600 12px tabular: *12C*. 5. **Compact**: the label is hidden visually (it stays in the accessible name); glyph and number remain, 12px padding. 6. **Position**: 16px from the right and bottom, inside the safe area; the page reserves `--k-fab-slot`. 7. **States**: hover brightens 10%, pressed 92%, focus a 2px `--k-focus` ring 3px out, busy shows the [spinner](https://kwark.space/designSystem/components/spinner.md) in place of the plus. ### Tokens | Token | Light | Dark | |---|---|---| | `--k-accent` | #98633f | #98633f | | `--k-on-accent` | #ffffff | #ffffff | | `--k-shadow-pop` | 0 1px 2px rgba(15, 23, 42, .06), 0 12px 32px rgba(15, 23, 42, .12) | 0 2px 6px rgba(0, 0, 0, .2), 0 16px 36px rgba(0, 0, 0, .55) | | `--k-radius-pill` | 999px | | | `--k-fab-slot` | calc(78px + env(safe-area-inset-bottom)) | | | `--k-tap` | 44px | | | `--k-fs-body` | 14px | | | `--k-fs-meta` | 12px | | | `--k-focus` | #0f172a | #f4f4f5 | | `--k-icon-lg` | 20px | | ## 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
ShotsScene 12 · 2 shots
ShotsScene 12 · 9 shots
``` ## Accessibility ### Keyboard | Key | Does | |---|---| | Tab | Reaches it after the page content, before the footer. It is last in reading order, as it is last visually. | | Enter / Space | Creates the item and moves focus to its first field. | ### ARIA and announcements - A real `
``` ## Accessibility - Named, keyboard reachable, and its menu is a Sheet. - Dragging is optional; it also works where it rests. ## For agents ### Rules - **Never** put more than one floating control on a phone screen. - **Must** reserve `--k-fab-slot` at the foot of phone pages. ### AI readiness test **Task:** Add a "quick note" action to the phone screenplay. **Give the agent:** Floating dial, Phones pattern. **Constraint:** No new floating buttons. **A reliable answer:** - Adds an item to the existing dial's sheet - No second FAB --- # Icon button > A button that is only a glyph. Allowed for universal symbols, and it always carries a name. Source: https://kwark.space/designSystem/components/icon-button ## Usage ### When to use Only for glyphs nearly everyone reads the same way: back, close, more (⋯), add, search. For anything else use a [Text button](https://kwark.space/designSystem/components/text-button.md): a control says what it is with a word. **Do:** ⋯ on a scene row, with the accessible name *More actions for Scene 12*. **Don't:** A lone sparkle, wand or lightning icon that means something different in every app. ## Style ### Anatomy 1. **Target**: 32 × 32px on a desk, 44 × 44px under a thumb (`.k-iconbtn`). 2. **Glyph**: 16px lucide, stroke 1.75, `--k-text-2`. 3. **Hover and open**: `--k-raise` ground, `--k-text` glyph. 4. **Name**: `aria-label` and the same words in `title` (IconButton sets both from its required `label`). ### Tokens | Token | Light | Dark | |---|---|---| | `--k-text-2` | #5b6779 | #9ca3af | | `--k-raise` | #f1f5f9 | #252525 | | `--k-icon-lg` | 20px | | | `--k-control-md` | 36px | | | `--k-radius-control` | 6px | | ## Code ### React In the Kwark app: `import { IconButton } from '@/components/ui/IconButton'`. ```tsx ``` | Prop | Type | Notes | |---|---|---| | `icon` | `LucideIcon` | | | `label` | `string` | required; becomes aria-label and title | | `iconSize` | `'sm' \| 'md' \| 'lg'` | 14 · 16 · 20px | ### HTML and CSS Works anywhere with `kwark.css`. ```html ``` ## Accessibility - Every icon button has `aria-label` (or visually hidden text) that names the action **and** its object when there are many: *Delete Scene 12*, not *Delete*. - Show a tooltip with the same name on hover and focus, for sighted people who do not know the glyph. - The glyph itself is `aria-hidden="true"`. ## For agents ### Rules - **Must** give every icon button an accessible name that includes its object. - **Never** use an icon button for an action without a universal glyph; use a Text button. - **Always** choose the shared icon sizes: 14, 16 or 20px. ### AI readiness test **Task:** Add row actions to a list of scenes. **Give the agent:** Icon button, List row, Menu. **Constraint:** Do not invent new glyphs. **A reliable answer:** - One ⋯ icon button per row opening a Menu - Name includes the scene, e.g. "More actions for Scene 12" - Destructive actions live inside the menu, not as separate icons --- # Split button > One action you run all the time, joined to the few close variants of it. The left half runs the default; the chevron half opens the formats. Source: https://kwark.space/designSystem/components/split-button ## Usage ### What it is Two buttons joined into one object. The left half runs the thing people do nine times in ten, and says exactly what it is: **Export PDF**. The right half is only a chevron; it opens the handful of close variants of the same act (Final Draft, Fountain, Print). A writer who exports every evening never opens the menu. A writer who sends an .fdx to a producer once a month finds it one press away, under the same button. ### The Kwark idea: the label names the format Generic split buttons change their main label to whatever was picked last, so the same button exports a different file on Tuesday. In Kwark the main half always names its format, and the menu marks the default with a tick and a line that says what will come out: page size, page count, and whether scene numbers print in both margins. Choosing **Final Draft** in the menu runs it once; it does not quietly become the new default. *Export settings…* is the place to change the default, and then the label changes with it (*Export FDX*). ### When to use - One dominant action with two to five variants of the same act: export formats, issue the call sheet now or schedule it, add a scene or an act. - In a toolbar or a module head where a second button beside it would compete. ### When not to use - The variants are different acts (*Export* and *Delete*): use a button and a [menu](https://kwark.space/designSystem/components/menu.md). - There is no dominant choice: use a [button](https://kwark.space/designSystem/components/button.md) that opens a menu, labelled with a chevron. - On a phone header: put the variants in the Menu sheet (Decision 0016); the split button stays in page content only. ### States | State | What changes | |---|---| | Rest | One object; the seam between halves is a 1px line, not a gap | | Hover | Only the half under the pointer steps its tone | | Pressed / open | The chevron half stays pressed while its menu is open; the chevron turns 180° | | Focus | Each half takes its own 2px ring, drawn above its neighbour | | Busy | The quark spinner replaces the main icon, the label counts (*Exporting 48 of 112*), the chevron is disabled | | Disabled | Both halves at 50%; say why next to it (*Read only: ask Mira for Write access*) | **Do:** **Export PDF** on the left, a drawn chevron on the right, and a menu where the default carries a tick and *US Letter · 112 pages*. **Don't:** **Formats ⌄** typed as text, a native disclosure triangle, or a main label that silently becomes whatever was chosen last. ## Style ### Anatomy 1. **Group**: `role="group"` with a name (*Export the screenplay*), 36px tall (28px at `--sm`), 8px outer corners, inner corners square. 2. **Main half**: icon 14px + verb and object, Poppins 500 14px, 14px padding. It never truncates the format; the object may truncate on very narrow screens. 3. **Seam**: secondary halves overlap their 1px borders into one line; on the primary the seam is an inset 1px line of `--k-on-accent` at 30%. 4. **Chevron half**: 34px wide (28px small), a 14px SVG chevron at stroke 2. Never a typed ⌄ or ▾. 5. **Menu**: the shared [menu](https://kwark.space/designSystem/components/menu.md), at least 300px. Rows carry a 14px format icon, the format's name, and a 12px line saying what it makes. The default carries a 14px tick in `--k-accent-soft`. Print and settings sit after a separator and end in an ellipsis. 6. **Busy**: the 14px [spinner](https://kwark.space/designSystem/components/spinner.md) and a tabular count replace the icon; the width is kept so nothing jumps. ### Tokens | Token | Light | Dark | |---|---|---| | `--k-accent` | #98633f | #98633f | | `--k-on-accent` | #ffffff | #ffffff | | `--k-raise` | #f1f5f9 | #252525 | | `--k-text` | #0f172a | #e3e3e3 | | `--k-text-2` | #5b6779 | #9ca3af | | `--k-accent-soft` | #e8b58b | #e8b58b | | `--k-surface` | #ffffff | #1a1a1a | | `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) | | `--k-shadow-pop` | 0 1px 2px rgba(15, 23, 42, .06), 0 12px 32px rgba(15, 23, 42, .12) | 0 2px 6px rgba(0, 0, 0, .2), 0 16px 36px rgba(0, 0, 0, .55) | | `--k-control-md` | 36px | | | `--k-fs-body` | 14px | | | `--k-fs-meta` | 12px | | | `--k-icon-sm` | 14px | | | `--k-dur-1` | 120ms | | | `--k-dur-2` | 200ms | | | Property | Value | |---|---| | Height | 36 · 28px | | Outer radius | 8px (`.ds-btn`), inner 0 | | Chevron half | 34 · 28px wide, 14px icon | | Hover | 7% `--k-text` into `--k-raise`; primary brightens 10% | | Pressed | 11% into `--k-raise`; primary 92% brightness | | Focus | 2px `--k-accent-soft`, 2px offset, `z-index: 2` | | Chevron turn | 180° over `--k-dur-2` with `--k-ease` | ## 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
``` Opening the menu: the chevron half sets `aria-expanded`, the menu takes focus on its checked row, Escape returns focus to the chevron half. On a phone the menu opens as a [sheet](https://kwark.space/designSystem/components/sheet.md). ## Accessibility ### Keyboard | Key | Does | |---|---| | Tab | Moves to the main half, then to the chevron half. Two stops, two names. | | Enter / Space on the main half | Runs the default (*Export PDF*). | | Enter / Space / ↓ on the chevron | Opens the menu with focus on the checked format. | | ↑ ↓ | Move through formats; Home and End jump to the ends. | | Enter | Runs that format once and closes the menu. | | Escape | Closes the menu and returns focus to the chevron half. | ### ARIA - The wrapper is `role="group"` with `aria-label` naming the act. - The chevron half has an accessible name of its own (*More export formats*), `aria-haspopup="menu"` and `aria-expanded`. - Formats are `menuitemradio` with `aria-checked` on the default; Print and settings are plain `menuitem`. - While busy, set `aria-busy="true"` on the group, keep the label readable, and announce *Screenplay exported* once in a polite live region. ### Touch Under a thumb both halves grow to 44px tall and the chevron half to 44px wide. They stay two separate targets. ## For agents ### Rules - **Must** name the default format in the main half ("Export PDF"), and never change it because someone picked another format once. - **Must** draw the chevron as an inline SVG in its own button with its own accessible name; never type ⌄ or ▾ or use a native disclosure triangle. - **Always** mark the default format with a tick and say what it produces (page size, page count) in the row's second line. - **Never** put a different act (delete, share, rename) in a split button's menu; it holds variants of the main act only. - **Must** become a Sheet on phones and keep both halves at 44px. ### AI readiness test **Task:** Put screenplay export in the screenplay's File area with PDF as the default and Final Draft, Fountain and Print as alternatives. **Give the agent:** This page, Menu, Print and export pattern. **Constraint:** Some writers have a page size of A4; the default label must stay truthful. **A reliable answer:** - Main half reads "Export PDF" - Chevron half is a separate named button with an SVG chevron - Default row is ticked and says "A4 · 112 pages" - Picking Fountain exports once without changing the default - Print… has ⌘P and sits after a separator --- # Text button > An icon and a word, used in headers, toolbars and sheets. A chevron means it opens something. Source: https://kwark.space/designSystem/components/text-button ## Usage ### What it is An icon and a word, for headers and sheets: Kwark’s answer to toolbars of bare icons. A control says what it is, with a word (docs/design-system.md). A chevron after the word means it opens something. ### Variants and where they live | Variant | Where | Look | |---|---|---| | Plain | The phone header’s **Menu ▾** (`TextButton opens`) | 32px (44 under a thumb), 14px, no border, `--k-raise` on hover and while open | | Bordered | Project home’s **Menu ▾**, the module head’s **Just the work** | 34px, 1px line, 12px, quiet text | | Filled | Project home’s **Start session** | 1px line on the raised ground, 12px | ### When not to use - For the one main action of a screen: that is a [Button](https://kwark.space/designSystem/components/button.md). - For a universal glyph alone (back, close, ⋯): that is an [Icon button](https://kwark.space/designSystem/components/icon-button.md). ## Style ### Anatomy 1. **Height**: 32px (`.k-textbtn`), 44px under a thumb; the bordered variant is 34px. 2. **Padding**: 0 12px (10px bordered); 8px between icon and word (6px bordered). 3. **Icon**: 16px; chevron 14px in `--k-text-2`. 4. **Word**: Poppins 500, 14px (12px bordered and filled). It never shrinks or clips: `flex: none; white-space: nowrap`. ### Tokens | Token | Light | Dark | |---|---|---| | `--k-text` | #0f172a | #e3e3e3 | | `--k-raise` | #f1f5f9 | #252525 | | `--k-control-sm` | 32px | | | `--k-icon-sm` | 14px | | ## Code ### React In the Kwark app: `import { TextButton } from '@/components/ui/TextButton'`. ```tsx ``` | Prop | Type | Notes | |---|---|---| | `label` | `string` | the word; required | | `icon` | `LucideIcon` | | | `opens` | `boolean` | adds the chevron | ### HTML and CSS Works anywhere with `kwark.css`. ```html ``` ## Accessibility - When it opens a menu: `aria-haspopup="menu"` and `aria-expanded`. - The word is the accessible name; do not repeat it in `aria-label`. ## For agents ### Rules - **Must** show a chevron when the control opens a menu or sheet, and never otherwise. - **Always** pair the icon with a word in headers and toolbars. ### AI readiness test **Task:** Design a phone header for the Characters screen with search, a filter and five other actions. **Give the agent:** Text button, Page header, Phones pattern. **Constraint:** One 44px line. **A reliable answer:** - Back, one-word title, at most two labelled actions - Everything else under "Menu ▾" - No subtitle or breadcrumb on the phone --- # Date picker > A month that knows the shoot: shooting days numbered Day 1 to Day 24, days off, recces and today, so a date is chosen as “Day 7 of 24”, not just the 23rd. Source: https://kwark.space/designSystem/components/date-picker ## Usage ### What it is The date picker opens a month that already knows the production. Shooting days carry their number (*D7*) in the shoot colour from the [Production calendar](https://kwark.space/designSystem/components/production-calendar.md); days off inside the schedule are dashed; recces wear the recce colour; today has a dot. The field itself reads *Mon 23 Nov 2026* with a **Day 7 of 24** tag, so a person never has to count. ### When to use - Choosing the date of a call sheet, a shooting day, a rehearsal, a recce or a deadline. - Moving a scene to another day from the stripboard (the tag confirms which shooting day it lands on). ### When not to - A date someone knows by heart and types faster than they pick (a birth date on a crew form): a text field with the format shown. - A range of many days (*the whole Mumbai block*): pick the first and last shooting day with two fields, or select strips on the [Stripboard strip](https://kwark.space/designSystem/components/stripboard-strip.md). - A time: the [Time picker](https://kwark.space/designSystem/components/time-picker.md) is a separate field. ### Shooting days, not just dates - Shooting days are numbered in order across months (*D13* on 30 Nov, *D14* on 1 Dec). The number comes from the schedule; never compute it from the calendar. - A day off is still choosable (a writer may book a reading on it), but choosing it for a shoot is an error with a way out: *Choose a shooting day, or add it to the schedule first.* - Before a schedule exists, the month is plain and the tag is absent. Nothing is invented. ### All-day dates stay put A shoot date is a calendar date at the location, stored as `2026-11-23`. Never store it as UTC midnight: someone opening the schedule in London would see the 22nd. **Do:** *Mon 23 Nov 2026* with **Day 7 of 24**; in the month, D1–D6, a dashed Sunday off, D7–D12. **Don't:** A bare `` that shows *23/11/2026* and leaves the 1st AD to count which shooting day that is. ### Writing - The field shows weekday, day, month and year: *Mon 23 Nov 2026*. Week starts on Monday. - Tags: *Day 7 of 24*, *Day off*, *Recce day*. Sentence case, figures not words. ## Style ### Anatomy 1. **Field**: 36px button (44 on touch) with a 16px calendar glyph, the date in 14px tabular figures, and the shoot tag: a pill in `--k-cal-shoot-bg` with `--k-cal-shoot-ink`, 600 12px. Open: `--k-accent-soft` edge. 2. **Popover**: `--k-surface`, 1px `--k-line`, 10px corners, `--k-shadow-pop` (it floats). 12px padding, up to 340px; full width under a thumb. 3. **Head**: previous and next month as 32px icon buttons; the month in 600 14px with the schedule summary under it (*Shoot · 24 days from 16 Nov*). 4. **Grid**: seven columns, Monday first, 2px gaps. Each day is a 40px button (44 on touch), 6px corners, the date in 500 14px tabular with an 11px note under it. 5. **Day kinds**: shoot (`--k-cal-shoot-bg` fill, ink text, *D7*), recce (`--k-cal-recce-bg`, *recce*), day off (1px dashed `--k-line-strong`, *off*), outside the month (50% opacity), today (a 5px dot in the corner). 6. **Chosen**: `--k-text` fill with `--k-bg` figures: the strongest mark on the month, in every room. 7. **Legend**: a 1px rule, then the three kinds as 12px keys and *Day 7 of 24* on the right. ### Tokens | Token | Light | Dark | |---|---|---| | `--k-cal-shoot` | #826d35 | #c4b068 | | `--k-cal-shoot-bg` | #f0ebd6 | #2d2919 | | `--k-cal-shoot-ink` | #4d4019 | #e5d89e | | `--k-cal-recce` | #4d6a7a | #83aac0 | | `--k-cal-recce-bg` | #e6eef2 | #1e2930 | | `--k-cal-recce-ink` | #2c4350 | #bad4e3 | | `--k-surface` | #ffffff | #1a1a1a | | `--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-bg` | #f8fafc | #191919 | | `--k-accent-soft` | #e8b58b | #e8b58b | | `--k-danger` | #b4382c | #e0685c | | `--k-shadow-pop` | 0 1px 2px rgba(15, 23, 42, .06), 0 12px 32px rgba(15, 23, 42, .12) | 0 2px 6px rgba(0, 0, 0, .2), 0 16px 36px rgba(0, 0, 0, .55) | | `--k-radius-card` | 10px | | | `--k-radius-control` | 6px | | | `--k-fs-dense` | 11px | | ## 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
Shoot date
RehearsalBefore the shoot. Not a shooting day.
Shoot dateSun 22 Nov is a day off. Choose a shooting day, or add it to the schedule first.
``` ## Accessibility ### Keyboard (inside the month) | Key | Does | |---|---| | Arrow keys | Move one day or one week. Crossing a month edge turns the month. | | Home / End | First and last day of the week. | | Page Up / Page Down | Previous and next month (Shift: year). | | Enter / Space | Choose the day, close, return focus to the field. | | Escape | Close without changing; focus returns to the field. | ### Roles and names - The field is a button with `aria-haspopup="dialog"` and `aria-expanded`; its name includes the date and the tag. - The month is a `role="grid"` table named *November 2026*; column heads carry the full weekday in `abbr`. - Every day button has a full name: *Monday 23 November, shoot day 7 of 24*; *Sunday 22 November, day off*; *Monday 16 November, shoot day 1 of 24, today*. - Only the chosen day is in the Tab order (roving `tabindex`); the chosen day has `aria-pressed="true"`, today has `aria-current="date"`. - The month title is a polite live region so turning the month is announced. - Shoot, recce and off are told by the note (*D7*, *recce*, *off*) and the name, not by colour. ## For agents ### Rules - **Must** number shooting days from the schedule (Day 7 of 24); never derive the number from the calendar. - **Must** store an all-day date as a local calendar date (YYYY-MM-DD); never as UTC midnight. - **Always** give every day button a full spoken name with its weekday, month and shoot status. - **Never** use a bare `` for production dates. - **Always** start the week on Monday and show the weekday in the field. - **Must** let a person choose a day off for non-shoot events, and explain the fix when it is chosen for a shoot. ### AI readiness test **Task:** Let the 1st AD move the Day 7 call sheet to a different date. **Give the agent:** Date picker, Production calendar, Call sheet. **Constraint:** The schedule has 24 shooting days from 16 Nov with Sundays off. **A reliable answer:** - Field shows weekday and Day N of 24 - Month marks shoot days with D-numbers, days off dashed - A day off chosen for a shoot gives an error naming the fix - Date stored as YYYY-MM-DD - Grid keyboard map and full day names --- # 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 ``, 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

Drop a screenplay

Final Draft, Fountain, Celtx, Fade In, Highland, Word, PDF or plain text. Up to 20 MB.

  • .fdx
  • .fountain
  • .celtx
  • .docx
  • .pdf

Blank Pages – draft 3.fdxFinal Draft · 412 KB

Reading pages · 48 of 11227 scenes so far

Blank Pages – draft 3.fdxFinal Draft · 112 pages · 64 scenes · 412 dialogue lines

Every line read cleanly

Scan_0041.pdfPDF · 3.1 MB

``` ## 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 --- # Number stepper > A number you nudge or type. It counts page length in eighths the way the stripboard does, takes like a slate, and keeps “not counted” apart from zero. Source: https://kwark.space/designSystem/components/number-stepper ## Usage ### What it is A stepper is a number field with a minus and a plus. Kwark’s counts what a production counts, in the units it counts in: - **Page count in eighths.** A scene’s length is *2 3/8 pages*, as on the strip and the call sheet. Each press is one eighth; typing *2 3/8*, *2.375* or *19/8* all store 2.375 and display *2 3/8*. - **Takes like a slate.** The slate variant is taller, with the word *Take* above the figure, for the camera report and continuity notes during a shoot, where a thumb presses it between setups. - **Not counted is not zero.** An empty field says *Not counted*. Zero background artists is a decision; an empty field is a gap the 1st AD still has to fill. ### When to use - Small whole numbers or fixed steps: takes, background artists, eighths, copies of a printed script, the number of days in a block. ### When not to - Large or free numbers (a budget line, a phone number): a [Text input](https://kwark.space/designSystem/components/text-input.md) with `inputmode`. - A judged, continuous value: a [Slider](https://kwark.space/designSystem/components/slider.md) fader. - Fewer than four possible values: a [Segmented control](https://kwark.space/designSystem/components/segmented-control.md). ### Behaviour - Holding a button repeats after 400ms, then every 80ms. - At the minimum or maximum the button disables and the hint says why (*The shortest scene is 1/8 of a page*). - Typing is never blocked mid-entry. The value is checked when the field loses focus; anything that cannot be read stays as typed with an error under it, so the person’s input is not thrown away. **Do:** *2 3/8 pages*, and an empty *Not counted* field for extras nobody has numbered yet. **Don't:** *2.375* in a browser spin box, and 0 pre-filled in every count so the schedule cannot tell unknown from none. ## Style ### Anatomy 1. **Box**: 36px (44 on touch), up to 240px, 1px `--k-line`, 6px corners, the input ground of the [Text input](https://kwark.space/designSystem/components/text-input.md). 2. **Buttons**: square, 36px (44 on touch), 14px minus and plus glyphs at stroke 2, divided from the value by 1px lines. Hover `--k-raise`; pressed a step darker; disabled 40%. 3. **Value**: Poppins 600 16px, tabular and lining, right-aligned against the unit; unit in 12px `--k-text-2` (*pages*, *people*). 4. **Slate variant**: 52px tall with 48px buttons and a `--k-line-strong` edge; *Take* above the figure, the figure at `--k-fs-head` (20px). 5. **Focus**: the box edge takes `--k-accent-soft`; buttons get the 2px `--k-focus` ring. 6. **Error**: danger edge and figure; the message under the field with an alert glyph. ### 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-soft` | #e8b58b | #e8b58b | | `--k-danger` | #b4382c | #e0685c | | `--k-fs-title` | 16px | | | `--k-fs-head` | 20px | | | `--k-control-md` | 36px | | | `--k-tap` | 44px | | | `--k-radius-control` | 6px | | ## 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
``` ## Accessibility ### Keyboard | Key | Does | |---|---| | Up / Down | One step (one eighth, one take). | | Page Up / Page Down | One whole page, or ten. | | Home / End | Minimum and maximum, when there is one. | | Typing | Free; checked on blur. | ### Roles and names - The input is `role="spinbutton"` with `aria-valuemin`, `aria-valuemax` and `aria-valuenow`, and `aria-valuetext` in words: *2 and 3 eighths pages*. - An empty field has no `aria-valuenow`, so it is announced as blank, not as 0. - Minus and plus are buttons named with their effect and object: *One eighth less*, *Next take*, *One more background artist*. They stay out of the Tab order only if the field itself handles arrow keys; otherwise they are focusable. - A disabled limit button keeps its reason in the visible hint. - Use `inputmode="decimal"` or `"numeric"` so phones show a number pad. ## For agents ### Rules - **Must** keep an empty count distinct from zero, in storage and on screen ("Not counted"). - **Must** display page lengths in eighths (2 3/8) and accept decimals and fractions as input. - **Never** block typing mid-entry; validate on blur and keep what was typed beside the error. - **Always** name the minus and plus buttons with their effect and the object they change. - **Never** use a browser spin box; use `.kw-stepper` with tabular figures. ### AI readiness test **Task:** Add a page-length field to the scene details panel and a take counter to the camera report. **Give the agent:** Number stepper, Stripboard strip, Call sheet. **Constraint:** Page length is in eighths; takes start at 1. **A reliable answer:** - Stepper steps by 1/8 and shows 2 3/8 - Accepts 2.375 typed - Slate variant for Take - Minus disables at 1/8 with the reason - aria-valuetext in words --- # Search field > Find words in the screenplay. Results read like the script: scene numbers in both margins, the heading in Courier, the match marked in the line. Source: https://kwark.space/designSystem/components/search-field ## Usage ### What it is Search finds words where a filmmaker keeps them: the screenplay, a scene, the notes. It is the library’s 44px search box (`.home-search`) grown into a find bar: a count (*2 of 5*), previous and next, clear, and a scope. Results are set like the script they come from: the **scene number in both margins**, the heading in Courier Prime, and the line that matched with the word marked in a soft `--k-accent-soft` wash, the colour of a highlighter on paper. ### When to use - Finding a word, a name or a prop across the screenplay (*cardigan*, *Mira*), within one scene, or in notes. - Filtering a long list in place: the library, the cast, the breakdown (without the results panel). ### When not to - Picking one value for a field: [Combobox](https://kwark.space/designSystem/components/combobox.md). - Jumping to a command or a module: the [Command palette](https://kwark.space/designSystem/components/command-palette.md). - Replacing text in the script: that is the editor’s Find and replace, which shows each change as a [Revision mark](https://kwark.space/designSystem/components/revision-mark.md). ### Behaviour - Results update as you type, after 150ms of rest. The query is kept when you open a result and come back. - Changing the scope keeps the query and says how many matches the new scope has, including *No matches*. - Enter goes to the next match; Shift + Enter to the previous. In the editor the page scrolls to the match and marks it. - No results is not a dead end: it names what was searched and where, and offers the next place to look. - Search never edits or judges the script. It finds and carries the reader there. **Do:** *2 of 5*, with *12 · INT. EDIT SUITE – NIGHT · 12* and the line where *cardigan* is marked. **Don't:** A list of page numbers with no headings, or a toast that says *No results* and clears the query. ## Style ### Anatomy 1. **Box**: 44px, 1px `--k-line`, 6px corners, the input ground. 16px search glyph, 14px text. Focus: `--k-accent-soft` edge and a 2px ring. 2. **Count**: 500 12px tabular, `--k-text-2`; *No matches* in `--k-danger`. 3. **Controls**: clear, then a 1px divider, then previous and next: 32px icon buttons (44 on touch), 16px glyphs. 4. **Empty**: placeholder *Search the screenplay* and the shortcut as a keycap. 5. **Scope**: a [Segmented control](https://kwark.space/designSystem/components/segmented-control.md) under the box: *Whole script*, *Scene 12*, *Notes*. 6. **Results**: a 10px-corner panel. Each hit is a grid: number (3ch), heading, number (3ch) in Courier Prime 700 12px; the matched line under the heading in 12px Poppins. Current hit: `--k-raise` and a 2px ink line on the left. 7. **Match mark**: `--k-accent-soft` at 45% behind the word, 2px corners, the text colour unchanged. ### 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-soft` | #e8b58b | #e8b58b | | `--k-danger` | #b4382c | #e0685c | | `--k-font-screenplay` | 'Courier Prime', 'Courier New', monospace | | | `--k-tap` | 44px | | | `--k-radius-control` | 6px | | | `--k-radius-card` | 10px | | ## 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
⌘F
No matches

No scene mentions “Nana” in the whole script. Her name may be in the notes:

``` ## Accessibility ### Keyboard | Key | Does | |---|---| | ⌘F / Ctrl+F | Focuses the search (in the editor). | | Enter / Shift + Enter | Next / previous match. | | Down / Up | Moves through the results list. | | Escape | Clears the query; a second Escape closes the find bar and returns focus. | ### Roles and names - `` named *Search the screenplay* (the scope’s name, not *Search*). - The count is a polite live region, so *2 of 5* and *No matches* are announced without moving focus. - Previous, next and clear are icon buttons with full names. - The results are a `listbox` of options; each option’s name reads naturally: *Scene 12, INT. EDIT SUITE – NIGHT, Mira wipes the screen with the cuff of her cardigan*. - The `` is also exposed as *highlighted* by screen readers that support it; never rely on its colour alone, the count says where you are. ## For agents ### Rules - **Must** keep the query when the scope changes or a result is opened. - **Always** show the match count and offer next and previous. - **Must** show scene numbers in both margins and the heading in Courier Prime in screenplay results. - **Never** leave a no-results state without saying what was searched and where to look next. - **Never** edit, rank or judge the script from search; it only finds and carries the reader to the words. ### AI readiness test **Task:** Add find to the screenplay editor’s toolbar. **Give the agent:** Search field, Segmented control, Screenplay page. **Constraint:** Scope can be the whole script, the current scene or notes. **A reliable answer:** - 44px search box named Search the screenplay - Count announced politely - Next and previous - Results with scene numbers both sides - No-results names the scope and offers Notes --- # Slider > Two sliders for film work: a playhead you scrub along a frame ruler with the timecode above it, and a fader with a unity detent and an exact value beside it. Source: https://kwark.space/designSystem/components/slider ## Usage ### What it is Kwark has two sliders, and both come from the cutting room, not from a settings page. - **Playhead scrub**: a ruler of frames under a timecode. Second ticks are tall, quarter-second ticks short, and the playhead is the same accent line with a cap that the [Playhead and scrubber](https://kwark.space/designSystem/components/playhead.md) uses on the timeline. Dragging anywhere on the ruler moves it; the timecode above it is the value. - **Fader**: a level, drawn as a mixing-desk fader cap on a thin rail, with marks at −24, −12, −6, **0** and +6 dB. 0 is the detent (unity) and is drawn heavier. An exact field beside the label takes typed values. ### When to use - **Scrub**: finding a moment in a scene, a clip or an animatic; trimming a shot’s in and out on a storyboard frame. - **Fader**: a continuous value a person judges by ear or eye, where nearby values are equally fine: dialogue and music gain, a preview’s opacity. ### When not to - A value that has to be exact (a page count, a lens in millimetres): use the [Number stepper](https://kwark.space/designSystem/components/number-stepper.md). - Choosing from a few named options: a [Segmented control](https://kwark.space/designSystem/components/segmented-control.md). - Long material on a phone: a slider over an hour of footage is too coarse. Pair it with a timecode field and frame steps. ### Behaviour - Scrubbing previews live; the position is not an edit and is not an undo step. - A fader previews while dragging and commits one undo step when released, not one per pixel. - The exact field and the fader are one value: typing −3 moves the cap; moving the cap writes −3. - Values snap to the detent within half a step of 0 dB when dragged, never when typed. **Do:** A frame ruler with 00:00:05:08 above it, and a fader whose 0 dB mark is heavier than the rest. **Don't:** A round blue thumb on a filled bar with no units, that reads the same for gain, zoom and progress. ## Style ### Anatomy ### Playhead scrub 1. **Card**: `--k-surface`, 1px line, 10px corners, 12px 16px padding. 2. **Head**: scene number in 600 and heading in 12px `--k-text-2`; timecode as `` in Poppins 600 `--k-fs-head` (20px), tabular, HH:MM:SS:FF. 3. **Ruler**: 44px (52 on touch), 6px corners, a step above the card with an inset 1px line. Second ticks 14px in `--k-text-2`; quarter-second ticks 7px in `--k-line-strong`. Labels in 11px tabular under the ticks. 4. **Playhead**: 2px `--k-accent` line, 4px past the ruler top and bottom, with a 12 × 8px cap. 3px wide on hover. 5. **Foot**: frame count and frame rate; the keys in small keycaps. ### Fader 1. **Rail**: 4px, `--k-raise` with an inset 1px line. No fill: a desk fader shows position, not quantity. 2. **Cap**: 14 × 26px, 3px corners, `--k-surface` with a 1px `--k-text` edge and an ink core (an inset, not a glow). Pressed: the edge and core take `--k-accent`. 3. **Marks**: 4px ticks with 11px tabular labels; the detent tick is 2px wide in `--k-text` and its label 600. 4. **Exact field**: 30px, 5.5 characters, 600 16px right-aligned, unit after it in 12px. ### Tokens | Token | Light | Dark | |---|---|---| | `--k-surface` | #ffffff | #1a1a1a | | `--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-focus` | #0f172a | #f4f4f5 | | `--k-fs-head` | 20px | | | `--k-fs-dense` | 11px | | | `--k-radius-card` | 10px | | | `--k-radius-control` | 6px | | ## 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
Scene 12 · INT. EDIT SUITE – NIGHT00:00:05:08
Frame 128 of 240 · 24 fps← → one frame · Shift one second
Dialogue gain
Music gainLocked while the stems export
``` ### Behaviour to supply - Frames: `timecode = [h, m, s, frame % fps]` from `frame / fps`, each padded to two digits. Set `aria-valuetext` to the timecode and the rate on every change (the site’s demo does this with `data-sequence-demo`). - Arrow keys step one frame; Shift + Arrow one second; Home and End the first and last frame. - Fader: keep the range and the exact field in step (the demo’s `data-gain-demo`), and set `aria-valuetext` with the unit: *−3 dB*. - Commit the fader on `change`, preview on `input`. ## Accessibility ### Keyboard | Key | Scrub | Fader | |---|---|---| | Left / Right | One frame | One step (0.5 dB) | | Shift + Left / Right | One second | 3 dB | | Home / End | First / last frame | −24 / +6 dB | | Page Up / Down | Ten seconds | 6 dB | ### Roles and names - Both are native ``, so phones and screen readers get a real slider. The drawn ruler, ticks and playhead are `aria-hidden`. - Names include the object: *Playhead in Scene 12*, *Dialogue gain*. - `aria-valuetext` speaks the value as people say it: *00:00:05:08 at 24 frames per second*, *−3 dB*. - The fader’s exact field has its own name (*Exact dialogue gain*) and is the precise route for people who cannot drag. - Focus shows a 2px ring around the playhead or the cap’s rail. Disabled faders say why in words beside the label. ## For agents ### Rules - **Must** use a native range input underneath any drawn ruler, playhead or fader cap. - **Must** set aria-valuetext with the unit or timecode on every change. - **Always** pair a fader with an exact field when the value matters; never make dragging the only way. - **Never** draw a slider as a filled progress bar or a round glowing thumb. - **Always** show timecode as HH:MM:SS:FF in tabular Poppins figures with the frame rate stated. - **Must** commit a fader as one undo step on release, not one per movement. ### AI readiness test **Task:** Add a scrubber to an animatic preview of Scene 12 and a dialogue gain control. **Give the agent:** Slider, Playhead and scrubber, Waveform. **Constraint:** 24 fps, ten seconds long; gain from −24 to +6 dB. **A reliable answer:** - Native range under a frame ruler - Timecode output in HH:MM:SS:FF - Arrow steps one frame - Fader with 0 dB detent and an exact field - aria-valuetext with units --- # Text input > One line of text with a visible label, an optional hint and a plain-language error. Source: https://kwark.space/designSystem/components/text-input ## Usage ### What it is A single line the person types into. Kwark’s current field is the story-surface one used in dialogs and the production office: a 36px box on a step of the ground, a 1px line, and the project’s light accent on the border when focused. Labels are sentence case, above the field. ### Variants | Variant | Where | Notes | |---|---|---| | Field | Date editor (*What*, *Where*), project dialogs | 36px, 14px text | | Numbers | Runtime, *How many* days in the date editor | `kw-input--mono`: tabular figures | | Search | Home’s *Find a story…* | 44px box, the glyph inside, no label but an `aria-label` | ### Writing - Label with the noun the person thinks in: *What*, *Where*, *Who it is for*. - Placeholders show an example, never the label: *Costume fitting, Meera*, *Draft to the producer*. ### Moving older code over `Input.tsx` draws a 12px upper-case tracked label and an 8px-cornered box with a ring. The production office draws upper-case labels too (`.po-label`). The system uses the story dialog’s sentence-case label; change the label when a file is touched. ## Style ### Anatomy 1. **Label**: Poppins 500, 12px, `--k-text`, 6px above the field. 2. **Box**: at least 36px, 7px 10px padding, 6px corners, 1px `--k-line`, ground `color-mix(--k-surface 35%, --k-bg)`. 3. **Text**: Poppins 400, 14px; placeholder `--k-text-2` at 65%. 4. **Focus**: border `--k-accent-soft`; keyboard focus adds a 2px ring in the same colour. 5. **Invalid**: border `--k-danger` and an error line under it in 12px. 6. **Read-only**: dashed border, no ground (ReadOnlyModule makes fields read-only for viewers). ### Tokens | Token | Light | Dark | |---|---|---| | `--k-surface` | #ffffff | #1a1a1a | | `--k-line-strong` | var(--k-text-2) | var(--k-text-2) | | `--k-text` | #0f172a | #e3e3e3 | | `--k-text-2` | #5b6779 | #9ca3af | | `--k-danger` | #b4382c | #e0685c | | `--k-focus` | #0f172a | #f4f4f5 | | `--k-radius-control` | 6px | | | `--k-control-md` | 36px | | ## Code ### React In the Kwark app: `import Input from '@/components/ui/Input'`. ```tsx setHeading(e.target.value)} /> ``` | Prop | Type | Notes | |---|---|---| | `label` | `string` | always visible; never placeholder-only | | `icon` | `LucideIcon` | leading icon | ### HTML and CSS Works anywhere with `kwark.css`. ```html ``` ## Accessibility - Tie hint and error to the field with `aria-describedby`; set `aria-invalid="true"` on error. - Never remove the focus ring. - Keep the field 16px or larger on iOS, or Safari zooms the page. ## For agents ### Rules - **Must** show a visible label; never use placeholder text as the label. - **Must** write errors that say what happened and how to fix it. - **Always** link hints and errors with `aria-describedby`. ### AI readiness test **Task:** Build the "New location" form: name, address, contact, notes. **Give the agent:** Text input, Textarea, Forms pattern, Content and voice. **Constraint:** Do not invent validation rules that are not stated. **A reliable answer:** - Visible labels - Only name required, marked in words - Errors that name the fix - Primary "Add location" --- # 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 One or two sentences. Kwark never scores it.
``` ## Accessibility - A visible `