# 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/<slug>.md) and https://kwark.space/designSystem/patterns/<saving-and-sync|empty-states|errors>.md.

Build <the screen> for <who>, who is <what they are doing>.

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 <the diff or the files>. 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/<errors|saving-and-sync|empty-states|destructive-actions>.md.

Write the interface words for <the moment: the import that reached the device but not the cloud; the empty Shots list; deleting Act 2>. The person is <who>, and they are worried about <what>.

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 <the screen> (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 <the part> for <who and situation>. 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 <the decision>. 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/<page>.md. Do not use anything you know about Kwark from elsewhere.

<Paste the Task from the page's AI readiness test.>
<Paste the Constraint.>

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
