Kwark. Design System
Open Kwark
Design SystemFoundations

Foundations

The decisions every Kwark screen is built on, from the six type sizes to the reason the editor never glows. Read these before you draw a component.

Foundations
Scene 12INT. EDIT SUITE – NIGHT · 1 3/8 pages
MIRAPlay it again.
SavedRevised

What a foundation is in Kwark

A foundation is a decision that holds on every screen, in every module, on every device. Colour roles, the six type sizes, the four corner radii, the spacing steps, the layers things float on, how long motion lasts, which icon pack: these are not choices a module makes for itself. A module that chooses its own blue, its own 13px or its own 18px corner is a module that looks like a different product, and Kwark has seen that happen. The production office once had its own typeface; the call sheet once had its own buttons. Both were brought back into the building.

Foundations live in two places at once:

  • In the app: styles/tokens.css in the Kwark repository holds every value, and docs/design-system.md states the rules. Checks in the build count violations per file and fail when a file gets worse.
  • Here: kwark.css (the same roles, framework-free) and tokens.json, so a person or an agent can build without the app’s source.

Where this site and the app disagree, this site says so on the page, and the app’s value is the one that ships.

The basics

The eight pages a builder needs first. Each one is a click from anywhere on this site.

How Kwark thinks

The decisions behind the values: why Kwark is calm, how it treats a writer’s work, and how it reads in other scripts and for other bodies.

Words, machines and data

How Kwark speaks, how it marks words a machine proposed, and how it draws numbers.

Rules that hold across every foundation

  • One value per job. If two things look different but do the same job, one of them is wrong (docs/design-system.md, principle 1).
  • The role, never the value. A component asks for --k-surface, not #ffffff, and --k-fs-body, not 14px. That is what lets the same row sit in light, dark and five writing rooms.
  • The writer’s choices are content, not UI. The room a writer works in, the typeface of the Reader, a pitch deck’s slide design: these may differ from the system, because the writer chose them. Everything around them is the system.
  • Flat. Depth is a line and a step in tone. Only things that float above the page carry a shadow (Elevation).
  • Phones first for the work. On a phone the screen belongs to the writing: one header line, one floating button, content by about y = 200 (Decision 0016).

Before you write a component, read the eight basics. Use only --k-* tokens. If the value you need is not a token, stop and say which value and why; do not add one silently. Where this site notes that the app ships a different value, follow the app’s value in app code and this site’s value in kwark.css work, and say which you used.

Where the values come from

Foundation In the app Here
Colour styles/tokens.css, utils/projectAccent.ts, EditorModule/utils/editorTheme.ts --k-bg … --k-danger
Type styles/tokens.css, EditorModule/pagination/typeface.ts --k-font-*, --k-fs-*
Radius styles/tokens.css --k-radius-*
Elevation styles/tokens.css (--ds-z-*), components/ui/Modal.tsx --k-z-*, --k-shadow-pop
Spacing styles/tokens.css --k-space-1…6, --k-tap, --k-fab-slot
Layout EditorModule/hooks/useEditorLayout.ts, hooks/useBreakpoint.ts COMPACT_QUERY
Motion components/ui/system.css, shared/SleekLoader.css --k-dur-*, --k-ease
Icons components/ui/Icon.tsx --k-icon-*

AI readiness test

Task. Build a new “Locations” summary card for the project overview that works on a phone and a desktop, in light and dark.

Give the agent. This page and the eight basics it links to.

Constraint. No new tokens, no new icon pack, no shadow on a resting card.

A reliable answer

  • Every value is a --k-* token
  • Card radius is --k-radius-card (10px) with a 1px --k-line border and no shadow
  • Title in --k-font-display at --k-fs-title, meta at --k-fs-meta
  • Lucide MapPin icon at 16px with the word Locations beside it
  • 44px tap target on a phone

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

Open .mdllms.txt
Loading…