Kwark. Design System
Open Kwark
Design SystemKwark method

Kwark method

How Kwark goes from a filmmaker's problem to a shipped screen, the tests every decision passes, and where each step is written down.

Kwark method
NeedSecond ADs reprint a call sheet nobody can date.
JourneyEdit all night, issue at 2 a.m., crew holds Rev 3.
AgreedIssue freezes a numbered copy; the draft stays editable.
RecordedDecision 0020, with what would make us remove it.

What this section is

Kwark is a story workspace built by a founder working alone with AI agents. There is no product team to catch a wrong turn in a meeting, so the method has to be written down well enough that a person or an agent who arrives cold can follow it and reach the same answer the founder would.

The method has one purpose, taken from the mission in docs/ux/mission-and-principles.md: help people who want to write feel calm, begin writing and keep writing, then take the same work into production. Every step below exists to protect that, and every step leaves a file behind.

The loop

A change a person will see goes through six steps, in this order. Bug fixes and polish use the short version at the end of this page.

  1. Is it needed? Name the person, the situation and the problem in one sentence, from how they actually work. “A competitor has it” is not a reason. Say what happens to the person if Kwark does nothing.
  2. Their journey. Walk the whole path: where they come from, what they see at each step, what can go wrong, how they get back to writing.
  3. Show the shape. A wireframe or a built mock-up at phone size first, then desktop, with empty, loading, error and offline states. Count what competes for attention above the fold.
  4. Agreement. The founder confirms the journey and the shape. Open decisions are asked, never silently defaulted; obvious ones are decided and stated as the builder’s call.
  5. Build in small steps that each ship safely, with tests, through the review ladder.
  6. Record. A decision record in docs/ux/decisions/, every new dot, badge, count or colour in the element register, and the UI map updated if a component was added.

The loop is not a waterfall. Step 3 often sends you back to step 1: drawing the call sheet issue panel is what showed that “Issued” was a field nothing ever set.

The tests every screen passes

These come from docs/ux/how-we-decide.md. A screen that fails one is changed or dropped, whoever asked for it.

Test The question
Calm Looking at it as a nervous first-time writer, does anything count, grade, warn, nag or ask for attention it has not earned?
Five seconds Can someone say what this screen is for and what to do next in five seconds? Is the thing they came for in the first 200px on a phone?
Meaning Can we say what every element is for, down to the last dot?
Remove it What evidence would make us remove this? It is written in the record.
Work is safe If this fails, loses connection or is interrupted halfway, what happens to the writing?
Everyone Phone, tablet, laptop; keyboard only; screen reader; slow or no network; a script in Tamil; a user in another country.
Honest copy Read every word aloud to a nervous writer. No hype, no shouting, no blame, no jargon.

And the empathy checklist, used in every review: who is this for and what were they doing a minute ago; what are they afraid of right now; what is the smallest thing that helps; what are we making them look at that is not their work; what can they not undo.

The standing rules

Some answers are settled and are not reopened by a new feature. Each has a decision record and a page here.

  • Kwark is a safe, private place (Decision 0001). No contests, leaderboards, public counts or comparing badges. Anything social belongs on Bekwarky, a separate site.
  • Kwark never judges the script (Decision 0002). No AI scores, coverage or verdicts, and no percentage that rates the writer.
  • Structure is always optional (Decision 0003) and structure, not teaching (Decision 0004). See Structure, not teaching.
  • Paper and digital as one act (Decision 0005). See Specs and handoff.
  • Competitors are the floor (Decision 0006). See Competitors are the floor.
  • Their work is never at risk (principle 12). A feature that can lose work is not shipped.
  • The free tier is a design constraint. About 50 people on Firebase’s free allowance. See Review and quality.

Before you build anything a person sees in Kwark, read docs/ux/mission-and-principles.md, docs/ux/how-we-decide.md and the decision records your change touches. If your change contradicts a record, stop and say which one; do not quietly override it.

Who does what

Role Does Never
Founder Agrees journeys and shapes; decides open questions; says yes to every push to main and every rules deploy Is asked a question that has an obvious default
Builder (person or agent) Finds the need, walks the journey, shows the shape, builds, writes the record Pushes, deploys rules or picks an expensive-to-reverse option without a yes
Supervisors (separate agents, review-only) Role simulation, UI, UX, database, security, founder judgement, engineer handoff Edit the code they review, or dismiss a finding without a written reason

Where it is written down

File What it holds
docs/ux/mission-and-principles.md The mission, the state Kwark protects, twelve principles with a test each
docs/ux/how-we-decide.md The order of work, the tests, the empathy checklist, the dot rule
docs/ux/decisions/ One record per decision, numbered. See Decision records
docs/ux/element-register.md Every dot, badge, count, colour and edge, with what it means
docs/ux/definition-of-done.md The gate and the review ladder
docs/ux/HANDOFF.md State for the next person or agent; updated every time work stops
docs/ux/audit/ Audits and supervisor reviews, one file each
~/AIContext/log.md The cross-tool handoff log; an entry every time an agent stops

Short version for bug fixes and polish

Say what the person experienced. Fix the cause, not the symptom. Add a test that fails without the fix. If the fix changes what a person sees, add a dated line to the relevant decision record’s history.

The method, step by step

AI readiness test

Task. The founder says “add a word-count leaderboard for co-writers”. Plan the work.

Give the agent. This page, Decision 0001, Decision 0002, docs/ux/how-we-decide.md.

Constraint. Follow the loop; do not write code.

A reliable answer

  • Stops at step 1 and names the conflict with Decision 0001 (no leaderboards or public counts)
  • Asks what problem the co-writers have, in one sentence
  • Offers a private alternative only if a real need survives (for example a rhythm only the writer sees)
  • Points social features to Bekwarky

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

Open .mdllms.txt
Loading…