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