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

Source: https://kwark.space/designSystem/foundations

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

- [Colour](https://kwark.space/designSystem/foundations/color.md): Colour 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.
- [Typography](https://kwark.space/designSystem/foundations/typography.md): Three 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.
- [Radius](https://kwark.space/designSystem/foundations/radius.md): Four corners, each for one kind of thing, a rule for corners inside corners, and the paper that is never rounded more than paper is.
- [Elevation](https://kwark.space/designSystem/foundations/elevation.md): Kwark 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.
- [Spacing](https://kwark.space/designSystem/foundations/spacing.md): Six 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.
- [Layout](https://kwark.space/designSystem/foundations/layout.md): Where 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.
- [Motion](https://kwark.space/designSystem/foundations/motion.md): Motion 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.
- [Iconography](https://kwark.space/designSystem/foundations/iconography.md): One 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.

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

- [Design principles](https://kwark.space/designSystem/foundations/principles.md): The 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.
- [Accessibility](https://kwark.space/designSystem/foundations/accessibility.md): WCAG 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 design](https://kwark.space/designSystem/foundations/inclusive-design.md): Who 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 rooms](https://kwark.space/designSystem/foundations/rooms.md): The 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 systems](https://kwark.space/designSystem/foundations/writing-systems.md): How 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.

## Words, machines and data

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

- [Content](https://kwark.space/designSystem/foundations/content.md): Kwark'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 writing](https://kwark.space/designSystem/foundations/ux-writing.md): The 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 authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md): Kwark'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 visualisation](https://kwark.space/designSystem/foundations/data-visualization.md): The 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.

## 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](https://kwark.space/designSystem/foundations/elevation.md)).
- **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).

> **For agents:** 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
