trykeyline 0.0.0-stage → 0.1.0

package/plugins/keyline/skills/keyline/domains/patterns/actions-and-forms.md

@@ -0,0 +1,204 @@
+# Actions and forms
+
+## Destructive items in a menu
+
+Every destroying or session-ending item takes the same place and treatment: last, after a divider, no icon, the danger treatment from the colour guide.
+
+```tsx
+<Menu>
+  <MenuItem onSelect={rename}>Rename</MenuItem>
+  <MenuItem onSelect={duplicate}>Duplicate</MenuItem>
+  <MenuItem onSelect={openMoveTo}>Move to…</MenuItem>
+  <MenuSeparator />
+  <MenuItem tone="danger" onSelect={() => openConfirm(row, triggerRef)}>Delete</MenuItem>
+</Menu>
+```
+
+The same holds in the profile menu (Sign out last, alone), in settings (a "Delete workspace" section last on the page, its button in the same danger treatment), and in a bulk-action bar (Delete at the end, set apart).
+
+| Item | Destructive or session-ending? |
+|---|---|
+| Delete, Remove from project, Clear history, Revoke access, Leave workspace, Sign out | Yes — one treatment |
+| Archive (restorable), Mark as done, Hide | No — ordinary items, ideally with Undo |
+| Cancel (an unsaved form) | No — a ghost button, not danger |
+
+## Proof in proportion to the loss
+
+| Loss | Ask for | Example |
+|---|---|---|
+| Reversible | Nothing; Undo in a toast for 5–8s | Archive a task, move a card, remove a tag |
+| One item, irreversible | A dialog; the button repeats the verb | Delete a note |
+| Many items, or someone else's work | A dialog that counts what goes ("48 tasks, 12 notes") | Delete a folder |
+| An account, a project, a workspace | Type a word to confirm | Delete project, delete account |
+
+Escalate on what is lost, not on how serious the screen looks: a bulk delete of 200 rows deserves more than a delete of one project with nothing in it.
+
+## The type-to-confirm dialog
+
+One component, used for every large delete. It is the system's dialog with different contents, never a bespoke surface (depth law 1).
+
+```tsx
+export function ConfirmDestroy({ open, onOpenChange, title, consequence, word = "DELETE",
+                                 action, pendingLabel, onConfirm, returnFocusTo }) {
+  const [typed, setTyped] = useState("");
+  const [state, setState] = useState<"idle" | "pending" | "error">("idle");
+  const [error, setError] = useState("");
+  const inputRef = useRef<HTMLInputElement>(null);
+  const matches = typed.trim().toLowerCase() === word.toLowerCase();
+
+  async function confirm(e: React.FormEvent) {
+    e.preventDefault();
+    if (!matches || state === "pending") return;
+    setState("pending");
+    try {
+      await onConfirm();
+      onOpenChange(false);
+    } catch (err) {
+      setState("error");
+      setError(messageFor(err)); // words, not a code
+    }
+  }
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(next) => state !== "pending" && onOpenChange(next)}
+      initialFocus={inputRef}
+      finalFocus={returnFocusTo}  /* the row or menu item that opened it */
+    >
+      <form onSubmit={confirm}>
+        <DialogTitle>{title}</DialogTitle>
+        <p>{consequence}</p>
+        <label htmlFor="confirm-word">Type {word} to confirm</label>
+        <input id="confirm-word" ref={inputRef} value={typed} autoComplete="off"
+               onChange={(e) => setTyped(e.target.value)}
+               aria-describedby={state === "error" ? "confirm-error" : undefined} />
+        {state === "error" && <p id="confirm-error" role="alert">{error}</p>}
+        <DialogFooter>
+          <Button variant="ghost" type="button" onClick={() => onOpenChange(false)}
+                  disabled={state === "pending"}>Cancel</Button>
+          <Button tone="danger" type="submit" disabled={!matches || state === "pending"}>
+            {state === "pending" ? pendingLabel : action}
+          </Button>
+        </DialogFooter>
+      </form>
+    </Dialog>
+  );
+}
+```
+
+- **The input takes focus, not Cancel.** The typed word is the guard; focusing it saves a click without weakening it.
+- **Case-insensitive**, trimmed: the reader proves intent, not typing accuracy.
+- **Held open while pending**: Escape and the scrim do nothing until it settles, so a failure has somewhere to be reported.
+- **Focus returns to what opened it**, the row's neighbour if the row is gone — depth law 12, with the code in `domains/depth/elevation-recipes.md`.
+
+## Undo instead of confirm
+
+For anything reversible, act at once and offer Undo:
+
+```ts
+async function archive(task: Task) {
+  const before = store.snapshot(task.id);
+  store.archive(task.id);
+  toast("Task archived", { action: { label: "Undo", onClick: () => store.restore(before) } });
+  try { await api.archive(task.id); }
+  catch { store.restore(before); toast.error("Couldn't archive task", { action: retry(() => archive(task)) }); }
+}
+```
+
+A confirm dialog in front of every reversible action trains the reader to click through dialogs, which is how the dangerous one gets clicked through too.
+
+## Field anatomy
+
+Label above, control, hint below; an error takes the hint's place rather than adding a line.
+
+```tsx
+<div className="field">
+  <label htmlFor={id}>{label}</label>
+  <Control id={id} aria-invalid={!!error || undefined}
+           aria-describedby={error || hint ? `${id}-note` : undefined} />
+  {(error || hint) && (
+    <p id={`${id}-note`} className={error ? "field-error" : "field-hint"}>
+      {error ?? hint}
+    </p>
+  )}
+</div>
+```
+
+Reserve the note's line height when a field has a hint, so the swap never moves the field below. Validate on blur and on submit, not on every keystroke; clear a field's error as soon as its value changes.
+
+**A form-level failure** — the server refused, the network dropped — is one line above the primary button, with an icon and `role="alert"`, saying what to do next. The fields keep what the reader typed.
+
+## The deciding field first
+
+Order a form by dependency, not by importance:
+
+| Instead of | Do |
+|---|---|
+| Description, then Category | Category (full width), then the fields it shapes, then Description |
+| Free text, then "Is this private?" | Private or shared first, if it changes who can be mentioned |
+| Every field shown, half disabled | Fields appear once the deciding answer allows them, in place, without reflowing what's above |
+
+The deciding field is full width because it is the one question every reader answers; the rest can sit in pairs.
+
+## The sign-in screen
+
+| Region | Holds |
+|---|---|
+| Form column, about 360px, unboxed | Title ("Sign in"), one muted line, fields, the one brand button, the secondary path as a link ("Create an account") |
+| Art panel, from a wide breakpoint | The depth guide's art panel on the other half (`domains/depth/elevation-recipes.md`); moving only if the auth routes are an `expressive` area in `## Profile`, otherwise one still frame |
+| Phone | The form alone; the art is decoration and goes first |
+
+- **No card around the form.** The page is the surface; a card on an otherwise empty page is a box around nothing.
+- **One primary button**, reading the verb: "Sign in", "Create account", "Send link".
+- **Errors**: field errors replace hints; "Wrong email or password" is a form-level line, never a field error that tells an attacker which half was right.
+- **Password managers** need `autocomplete="email"` / `"current-password"` / `"new-password"` and real `<form>` submission.
+- The panel's build and theme scope are the depth guide's art-panel recipe (`domains/depth/elevation-recipes.md`); its motion is the motion guide's ambient class, with a still frame under reduced motion; inputs at 16px on phones, so the browser doesn't zoom, are the type guide.
+
+## Pending states by how long the wait is
+
+| Wait | The reader sees | Where |
+|---|---|---|
+| Under 100ms | The control's own press state | On the control |
+| ≈ 400ms – 1s | The label turns to its progressive form ("Save" → "Saving…"), width held, the control disabled against a second press | In the button |
+| 1s – 10s | A skeleton of what's coming: the rows, the panel's shape, never a centred spinner over a blank region | In the region that will change |
+| Over 10s | Determinate progress — "Importing 340 of 1,200" — with Cancel, and a notice when it's done if the reader has left | In the region, then a toast off screen |
+
+Show the pending state only once the threshold passes, so a fast response never flashes it:
+
+```tsx
+function usePending(pending: boolean, after = 400) {
+  const [shown, setShown] = useState(false);
+  useEffect(() => {
+    if (!pending) return setShown(false);
+    const t = setTimeout(() => setShown(true), after);
+    return () => clearTimeout(t);
+  }, [pending, after]);
+  return shown;
+}
+
+// <button disabled={saving} style={{ minWidth }}>{usePending(saving) ? "Saving…" : "Save"}</button>
+```
+
+A skeleton, once shown, stays for at least ≈ 300ms, or a response that lands just after the threshold makes the region flicker twice.
+
+## Forgiving inputs
+
+Normalise on blur and on submit, and keep what was typed visible until then:
+
+| Field | Accept | Store |
+|---|---|---|
+| Email | Capitals, leading and trailing spaces | Trimmed, domain lower-cased |
+| Phone | Spaces, dashes, brackets, a leading `+` or `00` | E.164 (`+447700900123`) |
+| Card, IBAN, codes | Spaces and dashes, pasted in any grouping | Digits only; displayed back in groups of four |
+| Date | "12 Mar", "12/3", "tomorrow", a picker | ISO date; displayed in the reader's locale |
+| Amount | "1,200", "1200.00", a currency symbol | A number in minor units |
+
+`inputmode` and `autocomplete` do half the work — `inputmode="numeric"` for codes, `"email"`, `"tel"` — so the right keyboard arrives and the browser fills what it knows. An error names the fix ("Add the year"), not the rule broken ("Invalid format").
+
+## Progress through a flow, and its end
+
+- **Show position and what's left**: "Step 2 of 3" or a short list of named steps, the current one marked, earlier ones ticked and revisitable.
+- **Start with credit**: a setup checklist opens with the step the reader just finished already ticked.
+- **No step counter for one screen**, and none that changes length mid-flow; if a branch adds steps, show the new count when the branch is chosen.
+- **The end state** names what happened in the product's nouns ("Riverside project created"), shows the thing itself or a link to it, and offers the next action ("Invite your team"). It is a screen, not a toast that leaves the reader on the last form.

package/plugins/keyline/skills/keyline/domains/patterns/agents-and-live-states.md

@@ -0,0 +1,111 @@
+# Agents and live states
+
+Two patterns for output the reader didn't write and can't fully predict: an agent taking actions, and text arriving as it's produced. Both fail the same way — they ask for trust instead of showing their work.
+
+## The tool-call card
+
+Every tool call is one card in the conversation, in the order it happened.
+
+| Part | Holds |
+|---|---|
+| Header row | Status glyph · tool name in sentence case ("Search tasks", not `search_tasks`) · a one-line summary of the arguments ("Overdue, Riverside") · duration once done |
+| Arguments | Key–value pairs with labels from the glossary; long values truncated with "Show all" |
+| Result | A summary first ("12 tasks"), the raw result behind a disclosure |
+| Approval | Only when the step needs one — inline, under the card |
+
+**Open or closed.** A running step is open, so the reader can watch it; a finished one collapses to its header; a failed one stays open with the error in words and a Retry where retrying is safe. The reader's own open or closed choice wins over all three until the conversation reloads.
+
+**Status shape, not just colour.** The glyph changes shape between running, done, failed and waiting for approval (shape carries state, colour confirms it: the colour guide); a spinner inside the glyph is fine, a spinner instead of the card is not.
+
+```tsx
+<details open={state !== "done"} className="tool-call">
+  <summary>
+    <StatusGlyph state={state} />
+    <span className="tool-name">{label(tool.name)}</span>
+    <span className="tool-args">{summarise(tool.args)}</span>
+    {state === "done" && <time>{formatDuration(ms)}</time>}
+  </summary>
+  <ArgsList args={tool.args} />
+  <ToolResult result={result} />
+</details>
+```
+
+A native `<details>` keeps the content in the page for find-in-page and copy (layout law 11).
+
+## Inline approvals
+
+A step that changes something outside the conversation — sends a message, edits records, spends money — waits for approval under its own card:
+
+```
+┌ ◌ Send email · to 3 members ─────────────────────┐
+│ Subject   Site walk moved to Thursday             │
+│ To        Sam, Priya, Jo                          │
+└───────────────────────────────────────────────────┘
+  [Send email]  [Don't send]
+```
+
+- **The approve button names the action** and takes the brand action colour; reject is a muted ghost button. Not "Approve" and "Reject": the reader should be able to read the button alone.
+- **Never a modal.** The card above it, and the turns above that, are the evidence for the decision; a modal covers them.
+- **Never focused by default**, and never on Enter from the composer: an approval is a decision, not a keystroke the reader was already making.
+- **After the answer**, the buttons give way to a line saying what was decided ("Sent", "Not sent"), so the record stays readable.
+- **Several pending steps** each keep their own buttons; an "Approve all" may sit above them only when every step is the same kind of action.
+
+## Conversation layout
+
+- **No avatar per message.** Two speakers don't need faces to be told apart.
+- **The reader's turns** sit right-aligned, on a light tint, at most about two-thirds of the panel's width.
+- **The agent's turns** run full width with no fill — they are the content, and they hold tables, cards and code that need the width.
+- **AI-made content elsewhere** in the product — a summary on a record, a suggested title — carries one small mark in brand beside it, not a robot face or a coloured block (the colour guide).
+- **The panel is non-modal**: a side panel or sheet the reader can work beside, keyboard-reachable, closed by Escape when focus is inside it.
+- **The composer**: Enter sends, Shift+Enter adds a line; the send button is disabled while empty and becomes Stop while the agent is working.
+
+## Live text
+
+A live transcript or a streaming answer has two kinds of text, and they must look different:
+
+| Part | Treatment |
+|---|---|
+| Committed segments | Ink, final; never rewritten |
+| The phrase still forming | Muted, with a brand caret at its end |
+| Speaker or time markers | Meta tier, at each change, not on every line |
+
+**Following the bottom.** Follow while the reader is at the bottom; stop the moment they scroll up; show "Jump to latest" until they return:
+
+```ts
+function useFollowBottom(el: HTMLElement | null, deps: unknown[]) {
+  const atBottom = useRef(true);
+  useEffect(() => {
+    if (!el) return;
+    const onScroll = () => {
+      atBottom.current = el.scrollHeight - el.scrollTop - el.clientHeight < 24;
+    };
+    el.addEventListener("scroll", onScroll, { passive: true });
+    return () => el.removeEventListener("scroll", onScroll);
+  }, [el]);
+  useLayoutEffect(() => {
+    if (el && atBottom.current) el.scrollTop = el.scrollHeight;
+  }, deps); // eslint-disable-line react-hooks/exhaustive-deps
+  return atBottom;
+}
+```
+
+**The top fade** says more is above, and costs nothing to layout:
+
+```css
+.live-scroll {
+  mask-image: linear-gradient(to bottom, transparent 0, #000 32px);
+}
+```
+
+**Announcing.** Put committed segments in a polite live region, one segment at a time; keep the forming phrase out of it, or a screen reader re-reads every word as it changes. A visually hidden region beside the visible text is often simpler than making the visible list live.
+
+## Paused, stopped, failed
+
+| State | Shows | Offers |
+|---|---|---|
+| Live | Moving level bars or the one "working" signal | Pause; on hover and focus the live control becomes Stop |
+| Paused | Everything still; the forming phrase committed or dropped | View (the text so far), Copy, Resume |
+| Stopped | The full text, final | Copy, and whatever the product does next with it |
+| Failed | What was captured, kept | Retry, and the captured text never lost |
+
+What moves while live and stops while paused is motion law 1; what colour a live state takes is the colour guide's *Live is not danger*.

package/plugins/keyline/skills/keyline/domains/patterns/collections-and-dashboards.md

@@ -0,0 +1,131 @@
+# Collections and dashboards
+
+## Which view first
+
+| The items… | Primary view | Second view |
+|---|---|---|
+| Move through stages (to do → in progress → review → done) | Board: columns in the order work moves | List, grouped by status |
+| Happen at a time (visits, meetings, deadlines) | Week board with Week, 3 days and Day spans | List, grouped by day |
+| Are compared on many fields (members, invoices) | Table | — |
+| Are browsed by place (folders, projects) | Grid or list of places | — |
+
+**Board columns** run left to right in workflow order, each headed by its status glyph, name and count; the done column sits last and may collapse. A column that work skips is still shown, so the board reads the same every day.
+
+**Both views share everything but the container**: data, filters, sort, row rendering and the row menu (layout law 8). A filter set on the board is still set on the list.
+
+## Remembering the view
+
+On a working page the reader returns to daily, the view and span are remembered **per page**, not globally — the reader set the tasks board deliberately and the meetings list deliberately — with the switch always visible in the page header (layout law 9 owns the rule; this is the code).
+
+```ts
+const key = (page: string) => `view:${page}`;
+
+export function useRememberedView<T extends string>(page: string, fallback: T, opts?: { pinned?: boolean }) {
+  const [view, setView] = useState<T>(() => {
+    if (opts?.pinned) return fallback;            // the default is the point
+    try { return (localStorage.getItem(key(page)) as T) ?? fallback; } catch { return fallback; }
+  });
+  const choose = (next: T) => {
+    setView(next);
+    if (!opts?.pinned) try { localStorage.setItem(key(page), next); } catch {}
+  };
+  return [view, choose] as const;
+}
+```
+
+**Pinned pages** are those whose job is one view: folders open on folders, a calendar opens on this week. The reader can still switch for a visit; it just isn't remembered. List the remembered and pinned pages in `DESIGN.md` under `## Patterns`.
+
+## Optimistic moves with rollback
+
+```ts
+let seq = 0;
+
+async function moveCard(id: string, to: { column: string; index: number }) {
+  const mine = ++seq;
+  const before = board.positionOf(id);
+  board.move(id, to);                                  // now
+  try {
+    await api.move(id, to);
+  } catch (err) {
+    if (mine !== seq && board.positionOf(id) !== to) return; // a later move owns this card
+    board.move(id, before);                            // visibly put it back
+    toast.error("Couldn't move task", { action: { label: "Retry", onClick: () => moveCard(id, to) } });
+  }
+}
+```
+
+- **Animate the rollback** with the same travel as the move (the motion guide), so the reader sees the card go back rather than finding it there later.
+- **Keep sequence**: if two moves race, only the newest one's failure rolls back.
+- **Don't disable the board while saving.** Saving is background work.
+- **Never optimistic**: deletes without Undo, sends, payments, invitations — anything another person sees at once or the server decides.
+
+## The keyboard map
+
+| Key | Does | Where |
+|---|---|---|
+| ⌘K / Ctrl+K | Command palette: go to, create, run any action by name | Everywhere |
+| J / K | Next / previous row or card | Lists and boards |
+| Enter / O | Open the focused item | Lists and boards |
+| F | Open filters | Lists and boards |
+| C | Create in the current collection | Lists and boards |
+| Enter | Send | Composer |
+| Shift+Enter | New line | Composer |
+| Escape | Close the innermost layer only | Everywhere |
+| ? | Show the shortcut list | Everywhere |
+
+```ts
+const layers: Array<() => void> = []; // push on open, pop on close
+
+window.addEventListener("keydown", (e) => {
+  const t = e.target as HTMLElement;
+  const typing = t.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(t.tagName);
+  if (e.key === "Escape" && layers.length) { e.preventDefault(); layers.pop()!(); return; }
+  if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "k") { e.preventDefault(); openPalette(); return; }
+  if (typing || e.metaKey || e.ctrlKey || e.altKey) return; // single keys never fire while typing
+  shortcuts[e.key]?.(e);
+});
+```
+
+**Every drag has a keyboard path**: the row menu's "Move to…" opens a list of columns or dates; on a focused card, a shortcut can open it directly. **Shortcuts are shown where the action lives** — beside the menu item, in the tooltip, in the palette — from the one map in `DESIGN.md`, so the three never disagree.
+
+## Launchers and toolbars
+
+**A launcher asks the fewest questions the task has.** A record button that opens a form of six fields makes the most frequent action the slowest. Ask the one question that routes the result — which project, or a personal note — and default everything else, editable afterwards.
+
+**Toolbar filters are icons with tooltips**, each with its active state shown on the icon and a count when it holds several values. Text on every filter crowds the bar and pushes the page's own actions off narrow screens. The active filters show as removable chips under the bar, where they also explain an empty result.
+
+**Long admin lists** group into collapsible bars, closed by default:
+
+```
+▸ Admins        3 of 12 with access
+▸ Members       9 of 12 with access
+▸ Guests        0 of 4
+```
+
+Each bar's summary answers what the reader would open it to check. A search opens every group it matches and highlights the match; clearing the search restores what was open before.
+
+## Dashboards
+
+**The order**: overview (where things stand: a few figures), trends (which way they're moving: one or two charts over a sensible window), action items (what needs the reader: a short list, each item one click from done). Anything that answers none of the three goes — a recent-activity feed is the usual casualty, unless the product or its brief requires it; then it stays, built to earn its place (`commands/refine.md`).
+
+**Wireframe first**, in boxes and words, and share it before building. Questions to settle on the wireframe:
+
+- Which three to five figures, and what each one counts — its label names the noun.
+- Which figures report a problem (and so take a status colour while they do) and which are plain counts.
+- What the reader does next from each action item.
+- What the page shows on a new account with no data — usually the action items section offering the first action.
+
+**A long page is fine.** Hiding action items behind tabs to keep the page short moves the cost to the reader.
+
+**A scoped overview reuses the global pipeline**:
+
+```ts
+// one pipeline, two scopes
+const overview = (sources: Source[]) => buildOverview(sources);
+const global = overview(allSources);
+const project = overview(allSources.filter((s) => s.projectId === id));
+```
+
+Two queries for one view drift: a filter fixed in one, a status added to the other, and the project's overdue count stops matching the global one for the same project.
+
+**Figures that filter.** On a list page, the figures under the header can each apply their filter to the table below. They are then controls: focusable, `aria-pressed` when active, no hover lift (the motion guide), laid out as one hairline-parted row (layout law 3).

package/plugins/keyline/skills/keyline/domains/patterns/copy.md

@@ -0,0 +1,123 @@
+# UI copy
+
+Copy in a product is interface, not prose: it is scanned in passing, compared across screens, and read again a thousand times. Each rule below makes a label faster to recognise the second time.
+
+## Labels
+
+| Instead of | Write | Why |
+|---|---|---|
+| Record a voice note | Record | The surrounding screen already says what is recorded |
+| Request a feature | Help & feedback | The item also takes questions and bug reports; a label covers everything behind it |
+| Submit | Send · Save changes · Create project | Say what happens, not that a form was posted |
+| OK · Yes | Delete project · Sign out | The confirm button repeats the dialog's verb, so it reads correctly without the question |
+| Click here to view details | View details · or make the row itself the link | "Click here" carries no information out of context |
+| Are you sure you want to delete? | Delete "Riverside"? | Name the thing, drop the hedge |
+| Manage Team Members | Members | Sentence case; the verb is implied by the page |
+| NEW TASK | New task | Uppercase strips word shapes and reads as shouting |
+
+**Verb first, object only when needed.** One primary action on a screen needs no object ("Save"). Two verbs that could be confused do ("Save draft", "Publish"). A destructive button always takes its object ("Delete project"), because the object is what's lost.
+
+**Labels in menus are nouns or verbs, not both styles at once.** A menu of "Rename", "Duplicate", "Move to…", "Delete" is all verbs; "Settings", "Members", "Billing" is all places. An ellipsis means the item asks for more before acting.
+
+**Tooltips on icon buttons say the same words a text button would**, plus the shortcut: "Filter  F".
+
+## Sentence case, including generated labels
+
+Every label, title, column header, tab, field name and toast is sentence case. Keep acronyms, proper nouns and third-party product names as written ("Export to CSV", "Connect GitHub").
+
+Labels assembled from keys need a converter with an exception list, or the first acronym breaks it:
+
+```ts
+const KEEP = new Set(["ID", "URL", "API", "CSV", "PDF", "AI", "SSO"]);
+
+export function labelFromKey(key: string): string {
+  const words = key
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/[_-]+/g, " ")
+    .trim()
+    .split(/\s+/);
+  return words
+    .map((w, i) => {
+      const upper = w.toUpperCase();
+      if (KEEP.has(upper)) return upper;
+      const lower = w.toLowerCase();
+      return i === 0 ? lower[0].toUpperCase() + lower.slice(1) : lower;
+    })
+    .join(" ");
+}
+// dueDate → "Due date"; project_id → "Project ID"; AI_summary → "AI summary"
+```
+
+Prefer a hand-written label map for anything the reader sees often; the converter is the fallback for long-tail keys, tool names and imported fields.
+
+## Row second lines
+
+The formula is **`{type} from {origin}`**, in the product's nouns:
+
+| Instead of | Write |
+|---|---|
+| Issue added to Riverside | Task from Riverside |
+| Created by voice note on 3 Mar | Note from site walk |
+| New item in Inbox | Request from Northgate |
+| Riverside · Task · Open · 2h ago · Sam | Task from Riverside — with status as a glyph, time and owner in their own slots |
+
+- **Type** is the kind of thing, from the product's glossary. If the list holds one type only, drop it: "From Riverside".
+- **Origin** is where it came from or lives: a project, a meeting, a person, a source. Pick the one the reader sorts by.
+- **No verbs of history** ("added", "created", "moved"). They describe one moment, and the moment is already in the time slot.
+- **No status in the sentence.** Status has a glyph and a colour (the colour guide); words would say it twice.
+
+## The glossary
+
+One noun per kind of thing, everywhere: navigation, page titles, row lines, toasts, empty states, buttons. Record it in `DESIGN.md`:
+
+```markdown
+## Patterns
+
+**Nouns** — task (never "issue", "item" or "action"); note (a recording once processed); project; member (never "user" in UI).
+**Row second line** — `{type} from {origin}`; origin is the project, or "Personal" for notes outside one.
+```
+
+A synonym in one corner of the product reads as a second kind of thing. When a new screen needs a word, look it up first.
+
+## Messages
+
+**Toasts** say what happened, then offer the one thing to do about it:
+
+| Case | Write |
+|---|---|
+| Undo window | Task moved to Done · Undo |
+| Failure, retryable | Couldn't move task — Retry |
+| Failure, needs the reader | Couldn't save: the project was archived · View project |
+| Result off screen | Note added to Riverside · Open |
+
+Never "Successfully …" (the outcome is the message), never an exclamation mark, never an error code without words. A move the reader watched happen needs no toast.
+
+**Errors** say what to do, not what went wrong inside: "Enter a date after the start date", not "Invalid date range". Field errors replace the field's hint (`domains/patterns/actions-and-forms.md`).
+
+**Empty states** — one line on what goes here, and the action that makes the first one:
+
+| Case | Line | Action |
+|---|---|---|
+| New, nothing yet | Tasks from your notes and meetings land here. | New task |
+| Filtered to nothing | No tasks match "Overdue" and "Assigned to me". | Clear filters |
+| Search with no results | Nothing matches "riverbank". | Search all projects |
+
+**Confirmations** — the title asks with the thing's name; the body says what is lost in plain words; the button repeats the verb:
+
+> **Delete "Riverside"?**
+> Its 48 tasks, 12 notes and every file attached to them will be deleted for everyone. This can't be undone.
+> [Cancel] [Delete project]
+
+## Calls to action, links and sign-ups
+
+On a landing page or an article the words are most of the interface (law 14):
+
+| Instead of | Write | Why |
+|---|---|---|
+| Get started · beside Start free | Start free · Book a demo | Each call to action names what happens next, so two can't be mistaken for each other |
+| Learn more · Click here | Pricing · Read the case study | Link text names its destination, and still does in a list of links read out of context |
+| An email field labelled only by "you@example.com" | "Email" above the field; "One essay a month. Unsubscribe any time." below it | A placeholder vanishes on typing; the line says what arrives and how often |
+
+## Numbers in copy
+
+Counts beside a noun agree with it ("1 task", "3 tasks", "No tasks" — never "0 task(s)"). Use the platform's plural rules (`Intl.PluralRules`) once there is more than one language. A count that reports a problem takes its status colour; a plain count stays in ink (the colour guide).