Kwark. Design System
Open Kwark

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.

For agents

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

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.

Do

“Looks good, about 8 out of 10.” A feeling is not a grade, and a score hides which rule failed.

Don’t

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 systemWhat 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 systemHow 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 systemHow 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.ContributingHow 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.ReleasesWhat is in each version of the Kwark Design System, what changed, what is known to be missing, and what comes next.For agentsKwark 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 filesThe 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 libraryCopy-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 handoffHow 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 serverInstall 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.SkillsFourteen 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 roadmapKwark'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

ColourColour 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.TypographyThree 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.RadiusFour corners, each for one kind of thing, a rule for corners inside corners, and the paper that is never rounded more than paper is.ElevationKwark 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.SpacingSix 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.LayoutWhere 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.MotionMotion 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.IconographyOne 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 principlesThe 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.AccessibilityWCAG 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 designWho 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 roomsThe 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 systemsHow 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.ContentKwark'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 writingThe 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 authorshipKwark'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 visualisationThe 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 assistanceHow 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 syncKwark 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.ErrorsWhen 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 statesAn 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.FormsKwark 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.NavigationKwark 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.PhonesOn 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 shortcutsThe 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 actionsKwark 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 rolesSharing 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.CollaborationKwark 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.LoadingKwark 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 filterKwark 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 runA 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 exportEverything 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.NotificationsKwark 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.SettingsAnything 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 teachingKwark 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

ScreenwritingBuild 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.EditingBuild 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 shotsBuild 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 sheetsBuild 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.SoundBuild 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 gradingBuild 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 officeBuild 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 appCarry 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 and in components.json; each entry’s docs URL leads to the page with the test.

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

Give this Markdown to your coding agent or share its URL.

Open .mdllms.txt
Loading…