# 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 `