# Developing with the system

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

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

## Two ways in

- **Any codebase:** link `kwark.css`. It is one file with every token and the framework-free `kw-` component styles. No build step, no JavaScript.
- **The Kwark app:** use the React components in `components/ui/`. They are the source of truth; the `kw-` CSS on this site reproduces them.

Both read the same `--k-*` tokens, so a screen built from one and a panel built from the other sit together without a seam.

## kwark.css

```html
<link rel="stylesheet" href="https://kwark.space/designSystem/kwark.css">
```

Or copy the file into your repository and serve it yourself; it has no dependencies. It is assembled from `design-system/css/*.css` in name order: the tokens first (`00-core.css`), then component styles.

`kwark.css` does not load fonts. Load the three families the roles name, or the roles fall back to the system font:

```html
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Poppins:wght@400;500;600&family=Raleway:wght@500;600;700&family=Courier+Prime:ital,wght@0,400;0,700;1,400&display=swap">
```

Put `kw-root` on the element that holds the interface. It sets the UI font, the body size, the text colour and the page colour:

```html
<body class="kw-root">
  <button class="kw-button kw-button--primary" type="button">Save scene</button>
</body>
```

Every component page has the HTML under **Code**. Copy it as it is; the classes, the `type` attribute and the accessible names are part of the component.

> **For agents:** In a codebase without React components from Kwark, build with the kw- HTML from the component page and the --k-* tokens. Do not restyle kw- classes with new values; if a variant is missing, say so.

## tokens.json

`https://kwark.space/designSystem/tokens.json` publishes the light theme, dark theme and five rooms as DTCG 2025.10 tokens. Each theme includes inherited values. Colours use sRGB components, dimensions carry units, durations carry milliseconds, and aliases identify another token in the same theme.

```json
{
  "light": {
    "k-space-2": {
      "$type": "dimension",
      "$value": { "value": 8, "unit": "px" },
      "$extensions": { "org.kwark.css": { "value": "8px" } }
    }
  }
}
```

Use the typed value for a native platform. The `org.kwark.css.value` extension preserves the exact CSS declaration, including `var()`, `clamp()` and safe-area expressions. For responsive or safe-area dimensions, the typed value supplies the first absolute size as a fallback. A native adapter must implement the responsive and safe-area behavior for its platform.

The format follows the Design Tokens Community Group’s published exchange format. [DTCG format specification](https://www.designtokens.org/tr/2025.10/format/).

## React components in the Kwark app

The app imports through the `@/` alias (the repository root). The barrel file `components/ui/index.ts` exports the most common ones:

```tsx
import { Button, Modal, Input, Select, Tabs, Card, Badge, DropdownMenu, Drawer, EmptyState, UserAvatar } from '@/components/ui';
```

Other components are imported from their own files. Consult the Code tab for the source referenced by each page:

| Component | Import |
|---|---|
| Button | `import Button from '@/components/ui/Button'` (variants primary, secondary, ghost, danger; sizes sm, md, lg) |
| Breadcrumb | `import { Breadcrumb } from '@/components/ui/Breadcrumb'` |
| Toast | `import { useToast } from '@/components/ui/Toast'` (inside `ToastProvider`) |
| ConfirmDialog | `import ConfirmDialog from '@/components/ui/ConfirmDialog'` |
| ReadOnlyBanner | `import { ReadOnlyBanner } from '@/components/ui/ReadOnlyBanner'` |
| ViewToggle | `import { ViewToggle } from '@/components/ui/ViewToggle'` |
| Textarea, ContextMenu, TabBar, SectionLabel | `@/components/ui/<Name>` |

The phone and chrome parts:

| Component | Import |
|---|---|
| IconButton | `import IconButton from '@/components/ui/IconButton'` (a `label` prop is required; it becomes the accessible name) |
| TextButton | `import TextButton from '@/components/ui/TextButton'` |
| Icon | `import { Icon } from '@/components/ui/Icon'` (sizes sm 14, md 16, lg 20) |
| Segmented | `import Segmented from '@/components/ui/Segmented'` |
| Chip, ListRow, Sheet, MenuSheet, Combobox | `@/components/ui/<Name>` |
| PageHeader (phone header and the floating dial) | `import PageHeader from '@/components/ui/PageHeader'` |
| ProjectModuleBreadcrumb | `import ProjectModuleBreadcrumb from '@/components/ui/ProjectModuleBreadcrumb'` |

Each component page names its import when it is in the app. If a page says **Ready for Kwark**, there is no React component yet: build it from the page's HTML and tokens, in `components/ui/`, and add it to that page in the same change.

## Theming

### Dark

Add `class="dark"` (or `data-theme="dark"`) to `<html>`. Every role switches; components need no change. In the Kwark app, `ThemeContext` sets both the class and `data-theme` on `<html>`. The app opens in dark, and uses light only when the person chooses it, because the app's light theme is still being finished. `kwark.css` defaults to light; a product built on it can follow the system setting.

### Writing rooms

Inside the screenplay editor the writer chooses one of five rooms. Put `data-room` on the container that holds the page:

```html
<div data-room="paper">
  <p style="font-family: var(--k-font-screenplay)">INT. EDIT SUITE – NIGHT</p>
</div>
```

The values are `studio`, `daylight`, `paper`, `lamplight` and `midnight`. Inside a room the surface roles take the room's values, `--k-accent` becomes the room's pencil (`--k-pencil`), and `--k-on-accent` becomes the room's desk colour. A shared component placed inside the editor takes the room's colours with no extra code. See [Writing rooms](https://kwark.space/designSystem/foundations/rooms.md).

### A project's accent

A writer can give a project its own colour, and it replaces the accent everywhere in that project. Set the accent and the colour that reads on it together, always:

```css
.project-blank-pages { --k-accent: #2f6f5e; --k-on-accent: #ffffff; }
```

In the Kwark app this is `applyProjectAccent` in `utils/projectAccent.ts`. It sets the accent before the first paint (so a project never flashes the default colour), always sets the readable text colour with it, and treats the old imposed blues as no choice at all. `styles/tokens.css` maps `--k-accent` to that value, so components only ever read `--k-accent`.

**Do:** Test a new component with a pale project accent and a dark one, and check the text on the accent in both.

**Don't:** Assume the accent is copper, or write white text on the accent without `--k-on-accent`.

## Enforcement

The system is enforced in the build, the way a linter enforces a code style. Each check runs with the app's test suite and fails the change that breaks it.

- **`tests/design-system.test.cjs`** counts, per file, the places the code steps outside the system: a font named in a component (`fontFamily`), text under 11px (`tinyText`), a colour literal (`rawColour`), an icon size off 14, 16 or 20 (`iconSize`), and a pixel font size instead of the scale (`rawFontSize`). It fails when any file has more than its baseline allows, or a new file has any. Counts can only go down.
- The same file checks that the tokens live in `styles/tokens.css` and are not redefined in `index.html`, and that every breadcrumb renders through `components/ui/Breadcrumb.tsx`.
- **`tests/design-baseline.json`** holds the allowed counts. After a clean-up, lock the lower counts in with `node scripts/design-baseline.cjs`. Never run it to excuse a new violation.
- The scan itself is `tests/support/designScan.cjs`. Colour literals are allowed only in `styles/tokens.css`, `index.html` and the editor's room file `editorTheme.ts`.
- `docs/design-system.md` is the one-page summary of the rules the tests enforce.

The [MCP server](https://kwark.space/designSystem/agents/mcp.md) runs a similar check (`audit_code`) on a snippet before it is committed, for code that is not yet in a branch.

## Before you open a pull request

- Search the diff for `#`, `rgb(`, `px` font sizes and font names, and replace them with tokens.
- Look at the screen at 1440, 768, 375 and 320 wide. On a phone, check the touch layout with a mobile device mode, not only a narrow window.
- Tab through it: every control reachable, focus visible, Escape closes menus and dialogs, focus returns to the trigger.
- If you changed what a person sees, add a decision record or a line to an existing one. See [Contributing](https://kwark.space/designSystem/contributing.md).

## AI readiness test

**Task:** Add a "Rename scene" dialog to a React app that is not Kwark, using the Kwark system, then make it follow a project accent and the Paper room.

**Give the agent:** This page, the Dialog and Text input component pages, tokens.json.

**Constraint:** No Kwark React imports (they are not available outside the app). No new colours.

**A reliable answer:**
- Links kwark.css and loads the fonts
- Uses the kw- dialog and input HTML with type and accessible names
- Sets --k-accent with --k-on-accent together
- Uses data-room="paper" on the container rather than new values
- Returns focus to the trigger on close
