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
11 changes: 8 additions & 3 deletions docs/DESIGN_SYSTEM.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,16 +35,21 @@ Radius: `--radius: 0.5rem` (sm/md/lg/xl derived). Shadows: minimal, soft; prefer

## Components (shadcn variants)
- Button: `default` (primary), `secondary` (active toggle), `ghost` (toolbar icons, 40×40 touch targets on mobile), `outline`, `destructive`.
- Dialog (AI writer, delete confirmation), Sheet (library and panels below 1280px), DropdownMenu (export), Select (profile, provider), Tabs, Tooltip, Input/Textarea/Label, Switch (normalize), Sonner toasts. Only these shadcn components are kept in `src/components/ui/`; add new ones when a feature needs them.
- Dialog (AI writer, delete confirmation), Sheet (library and panels below 1280px), DropdownMenu (export), Select (profile, provider), Tabs, Tooltip, Input/Textarea/Label, Switch (normalize; 44×24px, the accent track when on and a muted track when off, a knob in its own colours that never takes the page background), Sonner toasts. Only these shadcn components are kept in `src/components/ui/`; add new ones when a feature needs them.
- Icons: lucide-react, 16px in toolbars.

## Page frames
- **Public pages** (`SiteHeader`, `SiteFooter`, `SitePieces`): content up to 1200px; tiles are `border bg-muted`, chips are small labels (`accent`, `line`, `warn`), a call to action is a band on `bg-accent`. Reading pages (guides, legal) use `DocLayout`: a sticky contents column on the left from 1280px.
- **App pages** (`AppShell`: Settings, Admin): a top bar on the page background with the same hairline as the public header (its contents the width of the page's content; **Back to the editor** is the primary button, the account a ghost icon), a menu of sections on the left (the active one on `bg-accent` with the primary along its left edge; chips on phones), a title with a line under it, and rows grouped in bordered cards on `bg-card` (a light lift off the page; the controls inside are outlines on the card's own colour, not darker wells).
- **Standalone screens** (`Standalone`: private-link gate, invitation, password reset, 404, load error): a bar like the app pages' (page background, primary Open the editor), and a centred bordered `bg-card` box.

## Preview styling (`.md-preview`)
GitHub-like prose on `bg-paper`: max-width ~72ch, headings in Fraunces, links primary with underline, blockquote left border `border`, tables bordered with zebra `muted`, code `code-bg` + mono, task-list checkboxes, images max-width 100%.

## Layout & breakpoints
- `< 768px` phone: single pane (Editor / Preview toggle), horizontally scrollable toolbar, panel buttons in a bottom nav, library and panels in sheets, condensed status bar.
- `768-1279px`: split view with scroll sync; the library opens as a left sheet and the panels as a right sheet.
- `>= 1280px` desktop: docked library sidebar (about 240px, collapsible) | editor | preview (scroll-synced) | docked side panel (about 288px, Checks/Outline/Front matter).
- `768-1279px`: split view with scroll sync; the library and the panels open as a sheet from the left.
- `>= 1280px` desktop: panel buttons (48px) | one docked pane (288px, resizable; the library or the chosen panel) | editor | preview (scroll-synced). Nothing docks on the right.
- Focus mode: hides chrome, centers the editor.
- Touch targets >= 40px on phones (toolbar buttons shrink to 36px from 768px up, where a pointer is the norm); dialogs scroll within the viewport.

Expand Down
2 changes: 1 addition & 1 deletion docs/SYSTEM_SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -669,7 +669,7 @@ CREATE TABLE share_comments ( -- plain text, one level of replies
- _Linking social sign-ins_ (`src/server/auth/social.ts`, shared by GitHub and Google): the provider's own id (`oauth_accounts`, unique per provider) is the identity, never the email. A known identity signs in (a suspended account is refused). Otherwise the provider must report the email as verified (`no_verified_email`). An account with that inbox (`emailKey`) gets the identity added and is signed in, so Google plus GitHub with one email, or a password account plus either, is one account; a suspended account is refused and nothing is linked. When that account's address was never confirmed, its password, sessions and pending links are removed first (whoever pre-registered it may not own the address), and the address counts as confirmed. With no such account a new confirmed, password-less one is made unless sign-ups are closed (`signups_closed`); the user row and its identity are removed together if the second insert fails. Different emails make different accounts. Password sign-up with an existing email answers `email_taken`, whose message points to the social buttons and "Forgot password" without saying which method the account uses.
- _Limits_ (table `rate_limits`, fixed windows, the same SQL on D1 and SQLite): 5 sign-ups per hour per address, 10 failed sign-ins per 15 minutes per email and per address (locked out until the window ends, before any password work, and a success clears the email's count), 3 confirmation emails per hour per account. The address is `cf-connecting-ip`, or `X-Forwarded-For` only when `TRUST_PROXY` is set, since any client can send that header; with neither, only the per-email limits apply.
- _Mail providers:_ `src/server/mail/` sends through a chain of providers (Resend and Mailtrap over HTTP anywhere; SMTP or a folder of JSON files on Node). Each has its free-tier limits (per UTC day and month) in a registry (`providers.ts`; adding one is one entry plus a small sender), counted in `rate_limits` only for sends that succeeded. A send goes to the provider with the most room left, skips any that is full, and falls through to the next on a failure; a provider that fails is left alone for 5 minutes, and a 429 marks it full for the day. `MAIL_PROVIDERS` orders or limits them, `MAIL_<ID>_DAILY`/`_MONTHLY` override the limits. No provider configured means no mail.
- _Email confirmation:_ when the server can send mail, a password account starts unconfirmed and **nothing is sent at sign-up**: the first time the account tries the cloud (a draft's "Save to cloud" or the account menu's "Choose drafts for the cloud…") the app opens a "Confirm your email" dialog that sends the link, and opening it again sends nothing while that link is still good ("Send it again" forces one). People who only write locally never cost a message. Until the link is used the cloud (sync and image hosting) answers 403 `email_unverified`. The one-time link (hash stored, 24 hours, single use, valid only for the address it was sent to) is used. GitHub and Google accounts count as confirmed. A server that sends no mail confirms nothing and blocks nothing. A failed send shows in the dialog, which offers to try again.
- _Email confirmation:_ when the server can send mail, a password account starts unconfirmed and **nothing is sent at sign-up**: the first time the account tries the cloud (a draft's "Save to cloud" or the account menu's "Choose drafts for the cloud") the app opens a "Confirm your email" dialog that sends the link, and opening it again sends nothing while that link is still good ("Send it again" forces one). People who only write locally never cost a message. Until the link is used the cloud (sync and image hosting) answers 403 `email_unverified`. The one-time link (hash stored, 24 hours, single use, valid only for the address it was sent to) is used. GitHub and Google accounts count as confirmed. A server that sends no mail confirms nothing and blocks nothing. A failed send shows in the dialog, which offers to try again.
- _Email design and retries:_ confirmation and reset mail are sent as plain text plus a designed HTML version (`src/server/mail/template.ts`): the warm paper palette as hex with a dark version for clients that follow the reader's setting, the link also written out under the button, and nothing loaded from the network (no images, fonts or trackers). If sending a confirmation fails, its link is removed again, so the next request tries a second time; once a send succeeds, later requests answer "already sent" until the link is used or expires.
- _Password reset:_ "Forgot your password?" in the sign-in dialog (shown only when the server can send mail) asks for the address and always answers "if an account exists, we sent a link", so it cannot reveal who has one: unknown addresses and inboxes already sent 3 links in the hour are answered identically, the mail is sent after the response goes out (`waitUntil` on Workers), and the same sign-up CAPTCHA applies. The link points to a page (`/reset-password`, noindex), not to a state-changing GET, so mail scanners that open links cannot use it up; the page takes the token out of the address bar. A link lasts an hour, works once, is stored only as a hash, is tied to the address it was sent to and to its purpose (a confirmation link cannot reset a password, nor the reverse), and a new request replaces the older one. A weak password is refused without using the link up. Resetting sets the password (so a GitHub-only account can also gain one), deletes every session of the account and its other pending links, sets the address as confirmed (the person just read mail sent to it) and lifts a sign-in lockout. It does not sign anyone in.
- _Changing the address:_ Settings, Account, Email, Edit asks for the new address and the current password and emails a link to the NEW address (purpose `email_change`, 24 hours, once, stored as a hash like the others, a newer request replaces the older one, 3 an hour per account). Nothing changes until the link is opened, so a mistyped address cannot lock anyone out, and the old address keeps working meanwhile. The current password is required so a stolen session cannot move the account to another inbox; an account with no password (GitHub or Google only) sets one first, and wrong guesses share the password limit. It needs a server that sends mail, since the new address must be proven. Opening the link (`GET /api/auth/email/confirm`, which redirects to the Account tab) sets `users.email` and `email_key` (the unique key decides if someone took the address meanwhile), marks it confirmed, ends the account's other sessions (the browser that opened the link stays signed in when it holds one of them), re-keys invitations held under the old inbox (`document_editors`, `share_people`; a row that would duplicate one already under the new address is dropped) so shared and live drafts keep opening, and emails a notice to the old address.
Expand Down
Loading