# UX before build

> On any feature that spans more than one screen, walk the person's journey and agree its shape by showing it, before a line of code is written.

Source: https://kwark.space/designSystem/method/ux-before-build

## Why this rule exists

On 27 September 2026 the founder asked for series and universes to be built. The builder went straight into storage and editor plumbing, and produced a film-to-series conversion and an episodes page that were its own guesses. The founder had to step in twice: a film stays a film, series are new projects, and every season and episode needs its own layer of every module with shared data underneath. His words: "we haven't thought this out for the users, we are just adding features".

Building first wasted the work, and it left the founder doing the product thinking. The rule that came out of it is now Kwark's feature process.

## When it applies

| Change | What is needed first |
|---|---|
| A new feature that spans two or more screens | The full process below |
| A new screen, panel or sheet | Journey and a shape at phone and desktop size |
| A change to navigation, sharing, saving or anything expensive to reverse | The full process, with two or three options and their costs |
| A one-screen change with an obvious answer | State your call in one line and build it |
| A bug fix or polish | The short version on [Kwark method](https://kwark.space/designSystem/method.md) |

## The process

1. **Is it actually needed?** One sentence: who has the problem, in what situation, and what happens to them if Kwark does nothing. If the only reason is a competitor, stop.
2. **The journey.** Write how each kind of person moves through it: where they come from, which screens they see, what they do, where they can go wrong, how they get back to writing. Name every kind of person: the owner, a co-writer, an actor with read access, a guest with no account.
3. **Show it.** A wireframe, an HTML mock-up or a built screen in the preview. Phone first (375 wide), then desktop. Include the empty, loading, error and offline states.
4. **Agreement.** The founder confirms the journey and the shape. Open questions that change what gets built are asked. Obvious defaults are decided and stated.
5. **Build**, in small steps that each ship safely.

### Agree by showing, not by interviewing

The founder answers in feelings and outcomes ("excited to explore what the app can do for them", "content with the work they have done"), not in specifications. On 11 November he stopped a round of brainstorming questions: "you are asking too many useless questions ... it's not that complicated". A mock-up gets a faster, truer answer than a question does.

- **Must** ask only what changes what gets built: two or three questions at most.
- **Always** decide anything with an obvious default (what a new project contains, standard behaviour), say it in one line as your call, and record it.
- **Always** show something the founder can react to before asking him to choose.

## Three real examples

### The first frame a new visitor sees (Decision 0035)

The problem: a new visitor met a four-slide introduction about the philosophy and the name, and the start button was on the last slide. Three mock-ups were drawn and shown side by side: A, the path of a film; B, the sample film as the front door; C, a blank page with the cursor waiting. The founder chose A in one message. The record keeps B and C with why each lost, and names B as the next thing to try if visitors read the five steps as a feature list and do not start.

### Four writer features from one competitor review

After a competitor review on 16 October, four ideas were written up in `docs/writer-safety-features-proposal.md`, each with a need check, a journey and a wireframe before anything was built. The outcome:

- **Typing in Indian scripts:** needed; all seven scripts at once.
- **Writing rhythm on every device:** needed, but no "your year" grid.
- **An independent timestamp on proof of authorship:** needed, deferred.
- **A beat table compared against target pages:** not built. Drawing it showed a red "drifted" flag judging the writer. It became targets on the timeline instead: a name and an aim in minutes or pages, no red, no verdict.

The fourth is the point of the process: the journey turned a copied feature into a better one before any code existed.

### Series and universes

The journey that should have come first, and was written after the correction: a writer starts a series as a new project; an existing film joins a universe by moving its characters and locations into shared canon; each season and each episode has its own layer of outline, characters and pre-production; the screenplay shows episodes in more than one dropdown. Only then was storage designed.

## What a journey document contains

| Part | What it says |
|---|---|
| Need | One sentence, the person and the situation |
| People | Every role that meets the feature, including guests and read-only collaborators |
| Steps | Each screen in order: what they see, what they do, what can go wrong |
| States | Empty, loading, error, offline, read-only, conflict |
| Phone | What changes at 375 wide and on a phone held sideways |
| Paper | Which paper artefact this replaces, and whether it prints |
| Cost | Reads and writes per action against the free tier |
| Open questions | Only those that change what gets built, with a recommended answer |

## Rules

- **Never** write code for a multi-screen feature before the founder has agreed its journey and shape.
- **Never** choose a default silently for anything expensive to reverse: data shape, permissions, naming, pricing, anything public. Write two or three options with costs and recommend one.
- **Must** draw phone first, at 375 wide, then desktop.
- **Must** include empty, loading, error and offline states in the shape you show.
- **Always** name the person and the situation in one sentence before naming the feature.
- **Always** keep the rejected options and the reason in the decision record.

**Do:** Show three mock-ups of the first frame side by side, recommend one, and ask "which one?"

**Don't:** Ask the founder eight questions about tone, audience and layout before drawing anything.

**Do:** Write the journey for an actor with read access, then design the screen they see.

**Don't:** Design the owner's screen and discover after the build that the actor sees a broken one.

## AI readiness test

**Task:** The founder says "start building the AI storyboard pack".

**Give the agent:** This page, memory note ai-storyboard-pack-and-3d-boards, Decision 0005, Specs and handoff.

**Constraint:** No code in this answer.

**A reliable answer:**
- Notes the pack's journey is not yet agreed and proposes one
- Names who uses it (director, storyboard artist) and the paper artefact (a per-scene PDF and image zip)
- Keeps generation outside Kwark (an exported pack and prompt, no API cost)
- Asks at most three questions and shows a wireframe of the export dialog
