v4.0 · 16 November 2026
Version 4 rebuilds the system from the app outwards. Every component was taken from Kwark’s source and reproduced in kw- CSS with the app’s geometry, type, colours, states and words. Every rule cites the decision it comes from.
What is in it
- One source, two readers. Every page is written once in
design-system/content/and built twice: an HTML page for people and a markdown twin for agents (the same URL plus.md). Each page has a Person and Agent switch. - Foundations. Colour roles with light, dark and five writing rooms; type, space, radius, elevation, layout, motion, icons; principles, accessibility, inclusive design, writing systems, content, UX writing, AI and authorship, data visualisation.
- Components, grouped by job (actions, inputs, selection, navigation, feedback, overlays, layout, data display, data visualisation, media, creative tools, AI and authorship, collaboration). Each has usage, style, code, accessibility and agent rules, and a status label: In the app, Ready for Kwark or New.
- Patterns for creative tools, Creative app kits for screenwriting, editing, storyboards, scheduling, sound, grading and production offices, and the Kwark method.
- kwark.css: every token and the framework-free component styles in one file.
- For agents:
llms.txt,llms-full.txt,AGENTS.md,tokens.json(DTCG 2025.10 token manifest),components.jsonandsearch.json, all generated on each build. - An MCP server (
kwark-design-mcp.mjs, no dependencies) with five tools:search_docs,get_page,get_component,get_tokensandaudit_code. See MCP server. - Skills to download: six for building (kwark-ui, kwark-ux-review, kwark-ux-copy, kwark-handoff, kwark-decision-record, kwark-creative-app) and eight for the product method (kwark-frame-problem, kwark-synthesise-research, kwark-map-opportunities, kwark-test-assumptions, kwark-prioritise, kwark-write-spec, kwark-measure-outcome, kwark-check-release). See Skills.
- A handoff template and a prompt library.
- An AI readiness test on every foundation, pattern, kit and component page, and a roadmap for teams adopting the system.
What changed from v3
- The site is static. Version 3 was a portal inside the app (
pages/Design, Decision 0045). Version 4 is generated intopublic/designSystem/bynode design-system/build.mjsand needs no app code to run. - The look was redone. Version 3 was rejected as generic: decorative illustrations, an accent picker, terracotta, monospace labels, cards and breadcrumbs that could have belonged to any product. Version 4 shows only parts as Kwark draws them.
- The MCP tools were renamed.
kwark_docs_search,kwark_tokens_lookup,kwark_component_spec,kwark_code_auditandkwark_dataviz_specbecamesearch_docs,get_page,get_component,get_tokensandaudit_code.get_pageis new and returns any page as markdown. The data-visualisation recipe now lives on its foundation page. Update any saved prompts that name the old tools. rules.mdis nowAGENTS.md. The name is the one coding agents look for.- Tokens are read from
kwark.css, not from the app’sstyles/tokens.css. The--k-*names are unchanged.
Known gaps
Said plainly, so nobody builds on an assumption.
- No Figma library. It is planned. Until then, the live pages are the visual reference.
- No published React package. The React components are in the Kwark app’s
components/ui/. Outside Kwark, usekwark.cssand thekw-HTML. kwark.cssdoes not load fonts. Load Poppins, Raleway and Courier Prime yourself.- The app’s light theme is unfinished. Kwark opens in dark. The light values here are specified, but not every app screen uses them yet.
audit_codeis a heuristic. It reads lines, not a syntax tree. A clean result is not a review.
Earlier versions
- v3.0, 15 November 2026. The in-app portal at
/designSystemwith the first MCP server and machine-readable files (Decision 0045). Replaced by v4. - Before v3. The system was a one-page rules file (
docs/design-system.md), the token file and a small specimen sheet at/design. The rules file is still the short summary the tests enforce.
What is next
These are plans, not dates. Each will be in a release note when it lands.
- Figma library, built from
tokens.jsonso the values match. - React components for every Ready for Kwark part, added to
components/ui/as Kwark needs them, each with its page updated in the same change. - A readiness index generated by the build, so Readiness tests lists every component test automatically.
- Guides, see Guides.
AI readiness test
Task. A team on v3 asks what they must change in their agent setup to use v4.
Give the agent. This page, MCP server, AI context files.
Constraint. Only changes listed here. No invented migration steps.
A reliable answer