Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion .claude/skills/podbay-ui/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,16 @@ The app is a single-page app served as static assets. It shows strangers' mail i
3. **The Worker decides; the app shows.** Hiding a button is a convenience, never a control. Every action must be safe when called directly.
4. **A sensitive change goes through `useFreshProof()`** ([`app/components/FreshProof.tsx`](../../../app/components/FreshProof.tsx)): it runs the change, and when the Worker asks for fresh proof it shows the sign-in steps and runs the change once more. Do not build a second confirmation.
5. **A secret is shown once and kept nowhere**: a key, a link, a recovery code lives in component state until dismissed. Never in storage, a URL, a query cache or a log.
6. **Every control has a name.** Kumo's `Input` takes `label`; a native control gets a `<label htmlFor>` or `aria-label`; an icon button gets `aria-label`. Errors are `role="alert"`. Move focus by a ref to the form, not by element id (the field library sets ids after the first paint).
6. **A control is Kumo's, and has a name** (`pnpm static controls`). No `<select>`, `<textarea>`, `<input>` or `<button>` is written by hand:
- a choice from a list is `Select`, or `Combobox` when it can be typed into;
- one choice of a few is `Radio`, a yes or no is `Checkbox`, and an on or off that takes effect at once is `Switch`;
- a line of text is `Input`, several lines are `InputArea`, a secret is `SensitiveInput`, and addresses are `TagInput`;
- a date is `DatePicker`;
- an action is `Button`, and a field with its label and help is `Field` with `Label`.

Read the component's entry in Kumo's own documentation, shipped with the pinned version (`node_modules/@cloudflare/kumo/ai/component-registry.md`), before using it. A control's size is its `size` prop, never a class: the controls of one form share one size, and a height, a size, a corner or a type size written by hand on a Kumo control is refused. Where Kumo's component cannot do the job, one wrapper for it lives in `app/components/controls/` and every screen uses it. A native control that must stay (a whole line that opens a message, say) is one line of `ON_PURPOSE` in `scripts/checks/controls.ts`, with its reason. The controls written by hand before the check came in are its `TO_MOVE` debt, which only goes down (#82, #83).

Every control has a name: Kumo's controls take `label`; an icon button gets `aria-label`. Errors are `role="alert"`. Move focus by a ref to the form, not by element id (the field library sets ids after the first paint).
7. **Attachments are downloads.** Link to a plain one; a risky one goes through the warning in `EmailAttachmentList`. Only plain image kinds are previewed or embedded (`isShowableImage`).
8. **No lint warning.** `pnpm lint` fails on one; a rule kept off at a place needs a `biome-ignore` that says why.
9. **The app asks in its own voice** (D16, `pnpm static dialogs`). Anything over the page is Kumo's `LayerDialog`: `LayerDialog.Root` for a form or a view, `LayerDialog.Alert` when the person must choose. `Content` takes exactly one `Title` and one `Body`, and at most one `Description` and one `Actions` with one `Action`; a form lives in `Body` with an `id`, and the `Action` submits it with `form="<id>"`. A confirmation is `useConfirm()` ([`app/components/Confirm.tsx`](../../../app/components/Confirm.tsx)). Never the browser's `confirm`, `alert` or `prompt`, and never Kumo's older `Dialog`. A menu is Kumo's `DropdownMenu`, not a hand-built list.
Expand Down Expand Up @@ -229,5 +238,7 @@ The app speaks English and Turkish. Every word a person reads or hears goes thro
- [ ] `pnpm check` passes and the lint count did not rise.
- [ ] `pnpm e2e` passes; a new page is in the policy test; a new journey has a browser test when it crosses a boundary.
- [ ] You tried it in a browser on the built app, not only in development mode, and with the keyboard alone.
- [ ] You opened every changed screen in a real browser at desktop width and at phone width, in the light and the dark theme, and compared its edges and heights with the screen beside it: every control of a form has one height, the left and right edges of the controls and of the footer line up, and the button that saves a form stands where its fields are.
- [ ] The pictures of each changed screen (desktop and phone, light and dark) are in the pull request, taken by you. A change under `app/` that changes nothing on a screen says so instead.
- [ ] Empty, loading and error states exist and say something true.
- [ ] Every new word is a message with its Turkish (`pnpm static messages`), and you read the screen once in Turkish: nothing cut off, nothing left in English.
1 change: 1 addition & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,4 @@
- [ ] If this touches a trust boundary (sign-in, authorisation, mail rendering, attachments, the sender check, the agent or MCP, tokens, exports, CI or releases), it ships a regression test, and I say which one below.
- [ ] If this relies on a Cloudflare fact (a limit, a binding, an API, a plan requirement), the current source and the date I read it are in the change.
- [ ] Commits are conventional and signed off (`git commit -s`).
- [ ] If this changes anything under `app/`: pictures of each changed screen at desktop and phone width, in the light and the dark theme, are below, or I say why there is nothing to see.
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ PODBAY_STATE_DIR=<dir> pnpm exec vite preview # the built app with its real re
node scripts/auth-ddl.ts --check # the auth migrations still produce Better Auth's schema (--delta: what to add)
pnpm format # Biome formatting and safe fixes
pnpm static [name] # one static check: pins, copies, licences, names, secrets, account, imports, sender,
# html, dialogs, messages, hosts, workflows, headers, compat, ledger, vendored, docs, guidance,
# html, controls, dialogs, messages, hosts, workflows, headers, compat, ledger, vendored, docs, guidance,
# ratchets, schemas
node scripts/checks/headers.ts --write # after changing shared/security-headers.ts
node scripts/pins.ts --resolve [names] # newest stable version that is at least 3 days old (network, read-only)
Expand Down
1 change: 1 addition & 0 deletions docs/status.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@
| Markdown links and anchors | D14 | `pnpm static docs` |
| The guidance is consistent: `AGENTS.md` is one page and names every skill and subagent; skills are named as their folders; a rule's paths still match files; a subagent names only skills that exist and cannot edit; the settings keep local secrets unread and ask before a push or a deploy | D15 | `pnpm static guidance`, `test/unit/guidance.test.ts` |
| No lint warning: every rule has one level for every file, no file is exempt, and `pnpm lint` fails on a warning (`--error-on-warnings`), so a clean run prints none. A rule is kept off at a place only by a `biome-ignore` that says why (two keyed lists that are never reordered). File size only goes down | D1, D4 | `pnpm lint`, `pnpm static ratchets` (lint warnings at 0) |
| The app's controls are Kumo's (`pnpm static controls`): no `<select>`, `<textarea>`, `<input>` or `<button>` written by hand in `app/`, unless kept on purpose with its reason; no height, size, padding, corner, type size or line height written by hand on a Kumo control, one of its dotted parts or a wrapper of `app/components/controls/`, with or without the important mark, and no `style` attribute on one; no plain element with the role of a control. A tag is read whole, across lines. The controls written by hand before the check came in (62 places in 30 files, six pill buttons, and one list with the role `listbox`) are a debt that only goes down, paid by #82 and #83. Not proven by the check: a control made with `createElement` or a tag in a variable, a Kumo control imported under another name, and a class from a variable or after a `${…}`; those are held by review. A changed screen is looked at in a real browser at both widths and in both themes, with the pictures in the pull request: the skill and the template ask it, and no check holds it | D9 | `scripts/checks/controls.ts`; `test/unit/controls.test.ts`; the `podbay-ui` skill (rule 6, "Before you finish") and `.github/pull_request_template.md` |
| `biome.json` names the schema of the Biome `package.json` pins: an update of the tool cannot leave its configuration behind | V1 | `pnpm static schemas`; `test/unit/schemas.test.ts` |
| Lint errors, formatting | D1 | `pnpm lint` |
| Types | D1 | `pnpm typecheck` |
Expand Down
2 changes: 2 additions & 0 deletions scripts/check-static.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
*/
import { check as account } from "./checks/account.ts";
import { check as compat } from "./checks/compat.ts";
import { check as controls } from "./checks/controls.ts";
import { check as copies } from "./checks/copies.ts";
import { check as dialogs } from "./checks/dialogs.ts";
import { check as docs } from "./checks/docs.ts";
Expand Down Expand Up @@ -38,6 +39,7 @@ const ALL: Check[] = [
imports,
sender,
html,
controls,
dialogs,
messages,
hosts,
Expand Down
Loading
Loading