chadtmiller.com/monolith
An atproto PDS
Working on the pages
This adds to the root AGENTS.md for work in web/.
-
web/is the OAuth authorization pages: sign in, the email code, choosing an account, consent, the passkey page, and the error page. It is one Svelte 5 app (runes, TypeScript), built by Vite, with no SvelteKit and no router.spec/OAUTH-PAGES.mdsays what the pages show and what each control calls;spec/OAUTH.mdandspec/PASSKEYS.mdsay what the server puts in each page (__authorizeData,__sessions,__passkeyOptions,__passkeyData,__errorData) and what the API takes and answers. The app reads those statements fromwindow. It calls only the API, and the browser's WebAuthn for passkeys (webauthn.ts), and the server makes everything else. -
npm cionce, thennpm run build. The build writesweb/dist, andpds-serverembeds it when it is compiled (just builddoes both).npm run checkis svelte-check with warnings as errors. -
src/email/email.htmlis the HTML part of the server's emails (spec/EMAIL.md, "The message"): one table-laid template, every style on its element, nothing loaded, as mail clients read little more. Its colours, sizes and spaces are tokens too,var(--x)(light) anddark(--x), which the build (vite.config.ts) writes in as values, toweb/dist/email.html. The server fills its{{…}}slots. Draw it withjust look email <kind>. -
The app is built from
spec/alone, ascrates/is (rootAGENTS.md). Read no source of the reference's pages (@atproto/oauth-provider-uiand the rest underharness/node_modules).harness/checks/pages.mjsmay be read, to see what is checked. -
Before changing a page, load the
uiskill (.claude/skills/ui). It has the house rules (sentence case, space, one primary button) andjust look, which draws any view, in any state, as pictures to open. Look at every state you touch before pushing. -
The components in
web/src/libare layered in atomic design's way:atoms: one element, such as an icon, an avatar, a button or a field;molecules: a few atoms that mean something together, such as an account (avatar, name, handle) or a labelled field with its error;organisms: a part of a view, such as the sign-in form, the list of accounts, or the list of what a scope asks for;templates: a view's layout without its data, such as the card with the server's host, a heading, a body and a row of actions.
A component uses its own layer and those below it, never one above. The views in
web/src/views(SignIn,EmailCode,ChooseAccount,Consent,AddPasskey,PasskeyAdded,ErrorPage) fill a template with the page's data and the API's answers.App.sveltepicks the view. Nothing inlibimports a view.harness/layers.mjschecks this, among the code gates. -
What is not a component goes in
web/src/libbeside the layers, as plain TypeScript with no markup: the API client (api.ts: headers, CSRF, errors as values), the page's data and its types (data.ts), the words for each scope (scopes.ts), and the alerts' texts (words.ts). Keep the words ofspec/OAUTH-PAGES.mdin one place, so a change of words is one change. -
Styles: each component's own
<style>, andweb/src/app.cssfor the base (the reset, the body, the type), whichmain.tsimports withweb/src/tokens.css. Every colour, size, space, radius and weight a rule uses is a token fromtokens.css. Take one by name rather than writing a value, and add one there when none fits. A colour for what it means is its role (--danger,--success,--attention,--neutral), never the hue under it (--red). Every colour that is text meets WCAG AA (4.5:1) on what it is drawn on, in light and in dark. A new colour that is text goes inweb/src/lib/contrast.json, andharness/contrast.mjschecks it, among the code gates. -
The pages' Content-Security-Policy allows stylesheets and scripts from the server alone (
spec/OAUTH-PAGES.md). So: nostyleattribute, nostyle:directive, no Svelte transition or animation (each injects a style), no inline handler in HTML, no font or image from anywhere but the server, the account pictures and the client's logo. A class changes how a thing looks. -
Icons are Lucide's (
lucide, ISC), each drawn from the package's icon data (its elements and their attributes) by one atom, in Lucide's 24-unit grid with its stroke, incurrentColor. They are used where people act and go, and as a table's check, not in sentences. -
In Svelte markup, keep a run of inline text in one expression or on one line. A block or component beside it splits the text into nodes, which shape differently from the same text whole.
-
Accessibility is part of the spec: the accessible names,
role="alert",aria-describedby,aria-busyand focus ofspec/OAUTH-PAGES.mdare what the harness finds controls by, and axe-core runs on every view.