# 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
