~ knotless Search/
↑↓ move↵ open⇧↵ all results
0
0
81 lines · 4.9 KB Raw History

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.md says what the pages show and what each control calls; spec/OAUTH.md and spec/PASSKEYS.md say what the server puts in each page (__authorizeData, __sessions, __passkeyOptions, __passkeyData, __errorData) and what the API takes and answers. The app reads those statements from window. It calls only the API, and the browser's WebAuthn for passkeys (webauthn.ts), and the server makes everything else.

  • npm ci once, then npm run build. The build writes web/dist, and pds-server embeds it when it is compiled (just build does both). npm run check is svelte-check with warnings as errors.

  • src/email/email.html is 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) and dark(--x), which the build (vite.config.ts) writes in as values, to web/dist/email.html. The server fills its {{…}} slots. Draw it with just look email <kind>.

  • The app is built from spec/ alone, as crates/ is (root AGENTS.md). Read no source of the reference's pages (@atproto/oauth-provider-ui and the rest under harness/node_modules). harness/checks/pages.mjs may be read, to see what is checked.

  • Before changing a page, load the ui skill (.claude/skills/ui). It has the house rules (sentence case, space, one primary button) and just 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/lib are 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.svelte picks the view. Nothing in lib imports a view. harness/layers.mjs checks this, among the code gates.

  • What is not a component goes in web/src/lib beside 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 of spec/OAUTH-PAGES.md in one place, so a change of words is one change.

  • Styles: each component's own <style>, and web/src/app.css for the base (the reset, the body, the type), which main.ts imports with web/src/tokens.css. Every colour, size, space, radius and weight a rule uses is a token from tokens.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 in web/src/lib/contrast.json, and harness/contrast.mjs checks it, among the code gates.

  • The pages' Content-Security-Policy allows stylesheets and scripts from the server alone (spec/OAUTH-PAGES.md). So: no style attribute, no style: 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, in currentColor. 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-busy and focus of spec/OAUTH-PAGES.md are what the harness finds controls by, and axe-core runs on every view.