Product facts

The business decisions a design document can never hold, answered once.

Part of the Konjo design language.

Some of what a screen needs is not a design decision. Whether a promotion can be undone, who is alerted when an incident is filed, what a removal cascades to — no amount of design documentation contains those, and a design system that invented them would be lying confidently on the screens where being wrong matters most.

So they live here, as given inputs. An agent building one of these screens reads the answer rather than asking for it.

How to use this file. If the fact you need is below, it is decided — build to it. If it is in Not yet decided, or it is not here at all, that is a blocker: name the missing fact and stop, per the skill's §1. Do not write a plausible sentence. A consequence line invented to satisfy a rule is worse than no consequence line.

How to add to it. A new fact is answered by the founder, not derived. Add the row, say which screens depend on it, and note any schema or RPC work the answer implies — several of these do, and that work is a follow-up rather than something to build silently.

Promotions

The screen: an instructor records that a student has been promoted. It is permanent, it changes the student's rank everywhere, and it issues a certificate.

The screen's opening line, under the title, saying what kind of thing this is before the person starts:

Permanent. A head instructor can correct it later.

It states only what is decided above. It is not a short version of the consequence line — that sentence names who is affected and who is notified, and a truncated paraphrase of it above the fold is consequence copy without the consequence.

What the consequence line may say, now that these are decided. The template is the sanctioned text; the worked example is only an illustration of it.

{Student}'s rank changes everywhere and a certificate is issued. {Student} and the head instructor are notified. A head instructor can correct this later.

Worked, once a student is chosen:

Ana Torres's rank changes everywhere and a certificate is issued. Ana Torres and the head instructor are notified. A head instructor can correct this later.

Before a student is chosen — the field-empty state — the neutral form, which is what the screen shows rather than showing nothing:

The student's rank changes everywhere and a certificate is issued. They and the head instructor are notified. A head instructor can correct this later.

Never a pronoun the app has to guess. Konjo does not hold anyone's pronouns, so a consequence line that says "she" is inventing a fact about a person on the screen that makes a permanent record. Repeat the name, or use the neutral form.

Test notes — the write-once rule

A promotion is usually recorded from a testing form the instructor filled in during the test. Some of what they wrote is for the student; some is candid and is not.

The instructor types it once. Notes are entered as separate lines, and each line carries a share control.

• Every line starts private. Nothing reaches the student unless it is explicitly marked.
• A share control on each line marks it for the student. One pass of typing, no retyping, no duplicate field.
• A running count sits above the submit: "2 of 6 notes will be sent to Ana." The instructor sees exactly what she will read before committing.
• The count is the confirmation. There is no separate review step — mid-class, that is one screen too many.

The reason for the default: an instructor writing quickly between rounds may phrase something bluntly without meaning harm. Private-by-default means the failure mode is forgetting to share something kind, which is recoverable, rather than sending something that stings, which is not.

Implies follow-up work: per-line note audience and promotion amendment history are both schema changes. Neither is built by the design work.

Incident reports

The screen: an instructor files a record of an injury, a safety concern, or a conduct issue. It is a legal record.

The amendment model is deliberate: a record nobody can fix is a record people stop filing, and an incomplete safety log is worse than an imperfect one.

Copy that follows from this: the form may state "Staff only. Students are never notified and never see this" before the tap, and confirm with "Report filed. The owner and head instructor were alerted."

Removing someone from a dojo

Removal is almost always the end of a conversation that already happened in person. An automated "You have been removed from Sunrise Dojo" is a cruel way to hear it, and it fires just as readily on an admin cleanup or a mistake — where it cannot be recalled.

But silence has to be stated, not implied. The person doing the removing must know the student will not be told, because otherwise they assume the app handled it and say nothing themselves.

What the consequence line may say — singular, then the plural form a roster's bulk action needs. Both are templates; the names are illustrations:

Removes {Student} from {Dojo}. Their attendance and promotions stay with the dojo. Their Konjo account is not deleted, and they can be re-added. {Student} is not notified.

Removes {N} students from {Dojo}. Their attendance and promotions stay with the dojo. Their Konjo accounts are not deleted, and they can be re-added. They are not notified.

Worked: "Removes Ana Torres from Sunrise Dojo. Their attendance and promotions stay with the dojo. Their Konjo account is not deleted, and they can be re-added. Ana Torres is not notified."

The notification clause goes last, after the reversibility clause. It is the one fact the remover is most likely to assume wrongly, and the end of the sentence is where it is read.

Merging two families

The front desk finds two household records that are really one family — the same family entered once at the desk and once by a parent — and joins them. The screen is /families/suggestions/[candidateId], and the same act is reachable from a family's own page.

The consequence line, word for word:

Merging moves every person, parent link, card, charge, payment and credit into the family you keep. Every saved card stays on file and keeps paying only for what it was set up to pay for. A cardholder whose card now covers more people gets an email. The other family is archived, not deleted. You cannot undo a merge in Studio — Konjo can separate the families again if it was a mistake.

Removing a check-in

The kiosk is a tablet a queue of people tap in turn, so the wrong name gets picked. The correction lives on the session roster at /attendance/classes/[scheduleId].

What the consequence line may say:

Removing a check-in deletes the attendance record, returns a class-pack credit if one was used, and takes the class off the member's own training log. It can't be undone — the removal is kept in Audit history.

The credit clause is not decoration. It is the only part of a removal that touches money the member paid, and the desk will not go looking for it.

Waivers

A waiver often carries medical information. The status is what an instructor needs at the door; the contents are not.

Money — refunds and revokes

The screen: staff issue a refund against a payment, or revoke something that was granted.

This is the strictest row in this file, and the reason is arithmetic rather than taste: every other permanent action here is permanent in Konjo's database, where a determined engineer could in principle repair it. A refund is permanent at Stripe. The UI is the last place it can be stopped.

Leads

The screen: the Leads board — prospects moving through stages toward becoming members.

Converting a lead to a member

"Convert to member" is not a one-click action. It opens a wizard the front desk works through while the person is standing there.

Implies follow-up work: the wizard itself does not exist. Neither does the open/claimable class list implied by sub requests. Both are features with their own plans — this file holds what they must mean, not permission to build them inside something else.

Editing the belt ladder

The screen: Studio's belt ladder (/style) → Edit ladder. Someone is renaming a rank, adding one, dropping one, or changing the order they come in.

The one-line version: a rank keeps its identity through a rename and a move, so moving one silently rewrites what every member at it, every promotion record naming it and every belt test targeting it means — which is why a save that moves a rank in use asks twice, and why a save that lands on a ladder someone else already changed is refused rather than merged.

Publishing curriculum

The screen: Studio's belt ladder (/style) → Publish to students. The owner has changed what the dojo teaches — a new technique, a different belt test — and is telling the school.

The one-line version: publishing curriculum tells every current member and instructor once, in-app (push rides the master toggle); it cannot be unsent; every version is kept and tests reference the version they were prepared on.

Reviewing a style update

The screen: Studio's belt ladder (/style) → Update available → Review curriculum update (/style/review/[versionId]). A style board has published a new version of the curriculum, and somebody at the school decides what their dojo does about it.

The one-line version: a board update changes nothing at a school until somebody with the curriculum permission accepts it; accepting it still tells no student anything — that is publishing.

Studio Home

The screen: the owner's dashboard.

The alert slot's ranking

When an uncovered class, a serious incident, a past-due payment and an unsigned waiver are all live on the same morning, the alert slot shows the first of these that applies:

1. An uncovered class — starting today with nobody to teach it
2. A serious incident — filed and unresolved
3. A past-due payment
4. An unsigned waiver

The order is by how soon it hurts and how badly it keeps. A class starting in two hours with no instructor is unrecoverable by evening; a past-due payment is exactly the same problem tomorrow, and the day after.

The order is the same for every dojo. It is not configurable. A slot whose selection rule varies by installation is a slot nobody can learn to trust — and this is the one element on the page whose whole value is that the owner believes it.

When a screen is empty

Every not-yet-set-up state needs to tell two situations apart: nothing has happened yet and you never turned this on. Getting it backwards prints a false statement about the business.

Each feature declares its own setup condition. There is no global "onboarding complete" flag — a dojo with billing live and no waiver templates is neither set up nor not.

Set up, nothing yet → "No leads yet." Not set up → "Publish your dojo page to start collecting leads," with the button that does it. The second is the more common state for a new dojo and the more useful sentence, which is why guessing wrong is expensive.

Adding a feature means adding its row here. A feature with no row has no legitimate not-yet-set-up state, and its empty screen must say only what it knows.

Direct messages

The screen: general person-to-person messaging — any two adult Konjo accounts, across dojos. Messages is the index-list inbox; a conversation is a thread of bubbles. One producer writes into the same pipes automatically: when a second instructor grades the same technique differently from the last recorded grade, Konjo sends a message from the newer assessor to the one they disagree with.

What the consequence copy may say — the block confirmation, the one destructive action on these screens:

Blocks {Name}. Neither of you will be able to message the other, and they won't be told. Your existing conversation stays visible to both of you.

Worked: "Blocks Riley Okafor. Neither of you will be able to message the other, and they won't be told. Your existing conversation stays visible to both of you."

Notifications

Five push categories, each individually switchable in Settings:

Turning a category off turns it off. There is no "important" override. The settings screen uses the same words the notifications do — see notifications.

Not yet decided

These are blockers, not blanks. If your screen needs one, say which and stop.

This section was full once

Twenty-one open facts were answered in a single sitting, and everything above the line came out of it. That is worth saying plainly, because a nearly-empty "not yet decided" section invites two wrong conclusions: that the questions were unimportant, or that the mechanism is finished.

Neither. The mechanism is the design skill's §1 rule — name the missing fact and stop — and its value is measured in the sentences it prevented, not in how long this list is. The row above got here the same way all twenty-one did: something needed building, the fact was not available, and the work stopped instead of inventing it.

Keep adding rows.

Why this file exists

A blind test of the promotion screen once produced a specification roughly a third of which was invention wearing the design system's vocabulary. The most dangerous line in it was a consequence sentence asserting what "remove from dojo" does — fluent, confident, and written from nothing, directly above the button that makes the record permanent.

The design system cannot prevent that by being more thorough, because the missing information was never design information. It prevents it by holding the answers here, and by stopping when the answer is absent. See governance.