About the system
What is the Kwark Design System?
The rules, parts and patterns that Kwark, a story workspace for filmmakers, is built from, published for people and for the agents that build with them. See About.
Is this a theme for Kwark, or the real thing?
The real thing. Components are reproduced from Kwark’s source with the same geometry, type, colours, states and words, and rules cite the decisions they come from. Where Kwark does not have a part yet, the page says Ready for Kwark.
Who decides what goes in?
Kwark’s founder accepts decisions; anyone can propose one. Every accepted change has a decision record that says why. See Contributing.
What do In the app, Ready for Kwark and New mean?
In the app: the component is in Kwark’s code, and the page gives its React import. Ready for Kwark: specified to the same standard, not yet in the app, so there is no React component. New: added or changed in this release. See About.
Using it
What licence is it under?
Code is MIT, the writing is CC BY 4.0, and the Kwark name and brand are not licensed. You can ship kwark.css in a commercial app if you keep its notice; you can reuse the rules with credit; you cannot call your product Kwark. The full terms are on Licence.
Can I use it for a product that has nothing to do with film?
The parts and foundations work for any product, and the patterns for saving, errors, empty states and phones are general. But the system is opinionated for creative work: it assumes the person’s work is private, never judged, and that structure is optional. If your product needs leaderboards, streaks or scores, it will fight you. Once the licence is decided, that will also say what is allowed.
Is there a Figma library?
Not yet. It is planned and will be built from tokens.json so the values match. Until then, the live pages are the visual reference, and a design that names components and tokens hands off cleanly. See Designing.
Should I use the React components or plain CSS?
Inside the Kwark app, the React components in components/ui/: they are the source of truth. Anywhere else, kwark.css and the kw- HTML from each component page: there is no published React package. Both read the same tokens. See Developing.
Does it work with Vue, Svelte, plain HTML or a native app?
Yes, through kwark.css and the kw- HTML for web frameworks, and through tokens.json for native apps (Swift, Kotlin) or a Tailwind theme. Interactive behaviour (menus, dialogs, focus) you write yourself, following each page’s Accessibility tab.
Why do the fonts not load?
kwark.css does not load fonts. Load Poppins, Raleway and Courier Prime yourself; the snippet is on Developing.
How do dark mode, writing rooms and project colours work?
class="dark" on <html> for dark. data-room="studio|daylight|paper|lamplight|midnight" on the working surface for a writing room. A project’s colour is --k-accent set together with --k-on-accent. Components need no changes for any of them. See Developing and Writing rooms.
Why is Kwark itself dark when the system defaults to light?
The app’s light theme is still being finished, so Kwark opens in dark and uses light only when someone chooses it. The light values on this site are specified; not every app screen uses them yet.
Can I add my own tokens or colours?
Add a token only when no role fits, with a light and a dark value and a comment, and propose it so it can join the system. Never write a raw colour into a component. See Colour.
Does it cover Indian scripts?
Yes. Writers in Kwark type in Hindi, Tamil and other Indian scripts. See Writing systems for type, input and how those scripts print.
Agents
Which file should I give an agent?
AGENTS.md always, then the markdown twins of the pages the task touches. Not llms-full.txt for a single screen. See AI context files.
How do I get a page as markdown?
Add .md to its URL, or switch the page to Agent and press Copy markdown.
Which agents does it work with?
Any agent that can read a file or a URL. The quick start covers Claude Code, Cursor, Codex and Gemini; the MCP server works with any client that speaks the Model Context Protocol.
Do I need the MCP server?
No. It helps an agent look things up and check its own code while it works, but AGENTS.md and the right page twins are enough for most tasks.
Does the MCP server send my code anywhere?
No. audit_code runs on your machine. If the server has no local copy of the site, it fetches the public files from kwark.space; your code is never sent.
What are the skills, and do I have to use Claude?
Each skill is a SKILL.md file that tells an agent how to do one job the Kwark way. Claude Code loads them automatically; other agents can be given the file as a prompt or a rule. See Skills.
How do I know an agent is really following the system?
Run the readiness test at the end of a page in a fresh conversation and grade each item as met or not met. See Readiness tests.
Will an agent using this write AI features that judge people’s work?
It should refuse to. The rules say a machine suggests and a person writes, that suggestions are marked until accepted, and that nothing scores or grades a person’s story. See AI and authorship.
Contributing and versions
How do I report a page that does not match the app?
Say the page, what the app does, what the page says, and the theme or room you saw it in. A screenshot helps. See Contributing.
How do I propose a new component?
Say who needs it and in what situation, which existing components you checked and why none fits, and what would make us remove it. Then write the decision record. See Contributing.
How is it versioned?
One number for the whole system: pages, kwark.css, tokens.json, components.json, the MCP server and the skills. Token names do not change inside a major version. See About and Releases.
Are the guides available?
Not yet. They are planned as paid guides; there is nothing to buy or sign up for. See Guides.
AI readiness test
Task. A startup asks whether they can ship kwark.css in their commercial screenwriting app and design in Figma with it.
Give the agent. This page.
Constraint. Only what this page says.
A reliable answer
- Says kwark.css can ship commercially under MIT with its notice kept, and points to the Licence page
- Says there is no Figma library yet and it is planned
- Points to the live pages and tokens.json as the reference
- Does not invent licence terms