---
name: kwark-ui
description: Build or change interface code with the Kwark Design System (kwark.css, --k-* tokens, kw- components, the React parts in components/ui). Use when writing a screen, panel, dialog, menu, form or component for Kwark or for a creative app built on the Kwark system, or when asked to make UI "match Kwark".
---

# Build UI with the Kwark Design System

You are writing interface code that must look and behave like Kwark, the story workspace for filmmakers. The system is documented at https://kwark.space/designSystem and each page links to its canonical Markdown twin.

## Load first

1. Read https://kwark.space/designSystem/AGENTS.md. It is short and holds the rules. Do not start without it.
2. For each part you need, read its component page: https://kwark.space/designSystem/components/<slug>.md (the list is in https://kwark.space/designSystem/components.json). If the Kwark MCP server is installed, use `get_component` and `get_tokens` instead.
3. For a screen that touches a pattern (saving, errors, empty states, phones, menus, destructive actions, sharing), read that pattern: https://kwark.space/designSystem/patterns/<slug>.md.
4. Only if you need values, read https://kwark.space/designSystem/tokens.json. Use the role names, not the values.

## Rules

- **Must** take every colour, font, size, radius, space and duration from a `--k-*` token. A hex code, an `rgb()`, a px font size or a font name inside a component is a bug.
- **Must** use the shared component when one exists. Inside the Kwark app that is `components/ui/*` (for example `import Button from '@/components/ui/Button'`); anywhere else it is the `kw-` class from kwark.css.
- **Must** give every control a word. Icon-only is allowed only for back, close, more, add and search, and then with an `aria-label` that names the object ("Close scene 12").
- **Must** show a chevron on anything that opens something.
- **Must** build the phone layout too (under 768px, and a phone on its side): one 44px header line, content by about y = 200, one floating control, rows without buttons.
- **Always** use native elements first: `button`, `a`, `input`, `select`, `dialog`. A `div` with `onClick` is a bug.
- **Always** write every state: empty, loading, error, offline, read-only, and the long-name case ("INT. EDIT SUITE – NIGHT – CONTINUOUS").
- **Never** add glows, gradients, blurred blobs or shadows on resting surfaces. Only menus, dialogs, toasts and the phone dial float, with `var(--k-shadow-pop)`.
- **Never** invent a token or a component. If none fits, stop and say which one is missing.
- **Never** let a machine write into the person's work without a revision mark and their acceptance. Never score, grade or judge their story.

## Theming

- Dark: `class="dark"` on `<html>`.
- Inside a screenplay editor: `data-room="studio|daylight|paper|lamplight|midnight"` on the container. The roles follow the room; do not hard-code editor colours.
- A project's own colour replaces `--k-accent`; set `--k-on-accent` with it. Test with a pale accent and a dark one.

## Before you finish

1. Search your diff for `#`, `rgb(`, `px` font sizes and font names; replace them with tokens. With the MCP server, run `audit_code` on every file you changed.
2. Check the layout at 1440, 768, 375 and 320 wide. Look at the screenshots, do not only run them.
3. Check focus is visible on every control and that Escape closes every menu and dialog.
4. Say which components and tokens you used, and anything the system did not cover.
