chore: setup design references

docs/design/screens/articles.md

@@ -0,0 +1,122 @@
+# Articles
+
+- **Route:** `/article`
+- **API:** GET /v1/article/ · PATCH …/publish · PATCH …/unpublish · DELETE /v1/article/{id}
+- **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "Articles" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
+
+Rows update when the server responds, not optimistically. Search, tab and sort are stored in the query string.
+
+## States
+
+### Default
+
+**Trigger:** The list loaded, sorted by last updated.
+
+- Breadcrumbs: Articles (mobile title "Articles")
+
+### Row menu open
+
+**Trigger:** The ellipsis button, or Enter on the focused menu button.
+
+- Breadcrumbs: Articles (mobile title "Articles")
+- Row "Winter checklist for timber windows": menu true, online false, updated "5 days ago"
+
+### Loading
+
+**Trigger:** The first load, or a retry.
+
+- Breadcrumbs: Articles (mobile title "Articles")
+- List: loading skeleton
+
+### Empty
+
+**Trigger:** The list is empty.
+
+- Breadcrumbs: Articles (mobile title "Articles")
+- Tab counts (All, Online, Drafts): 0, 0, 0
+- EmptyState (file-text): **No articles yet** "Write your first one. It stays a draft until you publish it.", action "New article" (primary)
+
+### No results
+
+**Trigger:** Search matched nothing. The tab counts still show the full list.
+
+- Breadcrumbs: Articles (mobile title "Articles")
+- Search query: "tiles"
+- EmptyState (search): **No articles match "tiles"** "Check the spelling, or search for a shorter part of the title.", action "Clear search"
+
+### No drafts
+
+**Trigger:** Drafts tab with nothing in it. The "Online" tab has an equivalent "Nothing is online yet" state.
+
+- Breadcrumbs: Articles (mobile title "Articles")
+- Active tab index: 2 (0 All, 1 Online, 2 Drafts)
+- Tab counts (All, Online, Drafts): 4, 4, 0
+- EmptyState (pencil-line): **No drafts** "Everything you've written is online.", action "New article"
+
+### Action in progress
+
+**Trigger:** Publish chosen from the row menu. That row is disabled.
+
+- Breadcrumbs: Articles (mobile title "Articles")
+- Row "Winter checklist for timber windows": busy "Publishing…", online false, updated "5 days ago"
+
+### Published
+
+**Trigger:** 200: the row updates in place and a toast confirms.
+
+- Breadcrumbs: Articles (mobile title "Articles")
+- Toast (success, circle-check): **Article published** ""Winter checklist for timber windows" is now online."
+
+### Action failed
+
+**Trigger:** A 500 or network error. The row stays as it was, and the toast stays until retried or dismissed.
+
+- Breadcrumbs: Articles (mobile title "Articles")
+- Toast (error, circle-x): **Couldn't unpublish** "The server didn't respond. Nothing changed." with action "Retry"
+
+### Row vanished (404)
+
+**Trigger:** Any row action gets a 404.
+
+- Breadcrumbs: Articles (mobile title "Articles")
+- Toast (info, info): **That article no longer exists** "It was deleted somewhere else, so we removed it from the list."
+- Tab counts (All, Online, Drafts): 5, 4, 1
+
+### Delete: confirm
+
+**Trigger:** Delete… from the row menu.
+
+- Breadcrumbs: Articles (mobile title "Articles")
+- Modal: **Delete this article?**
+  - text ""Winter checklist for timber windows" and its 3 images will be deleted. This can't be undone."
+  - cancel "Cancel"
+  - confirm "Delete article" (danger)
+
+### Delete: in progress
+
+**Trigger:** DELETE in flight. The dialog can't be dismissed.
+
+- Breadcrumbs: Articles (mobile title "Articles")
+- Modal: **Delete this article?**
+  - text ""Winter checklist for timber windows" and its 3 images will be deleted. This can't be undone."
+  - cancel "Cancel"
+  - confirm "Deleting…" (danger), loading, not dismissible
+
+### Delete: failed
+
+**Trigger:** 500, a partial failure where the article is kept. The error shows inside the dialog.
+
+- Breadcrumbs: Articles (mobile title "Articles")
+- Modal: **Delete this article?**
+  - text ""Winter checklist for timber windows" and its 3 images will be deleted. This can't be undone."
+  - Alert: "Couldn't delete the article, so it's still there. Try again in a moment."
+  - cancel "Cancel"
+  - confirm "Delete article" (danger)
+
+### Deleted
+
+**Trigger:** 204: the row is removed and focus moves to the next row. This is also where a delete from the editor ends up.
+
+- Breadcrumbs: Articles (mobile title "Articles")
+- Toast (success, circle-check): **Article deleted** ""Winter checklist for timber windows" and its images are gone."
+- Tab counts (All, Online, Drafts): 5, 4, 1

docs/design/screens/boot.md

@@ -0,0 +1,16 @@
+# App boot
+
+- **Route:** `any route, first load`
+- **API:** GET /v1/auth/me (pending)
+- **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "Boot" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
+
+While the session is checked, the shell renders with skeletons, never a spinner. The possible outcomes are: 200 with a verified user, which renders the route; 200 with an unverified user, which goes to /register/pending; and 401, which goes to /login?redirect=<path>. Public routes skip this check.
+
+## States
+
+### Checking session
+
+**Trigger:** The first paint on any back-office URL, and usually visible for well under a second.
+
+- Breadcrumbs: Home (mobile title "Home")
+- boot: true

docs/design/screens/editor.md

@@ -0,0 +1,182 @@
+# Editor
+
+- **Route:** `/article/:id/edit`
+- **API:** GET /v1/article/{id} · PATCH /v1/article/{id} · PATCH …/publish|unpublish · POST …/image · DELETE
+- **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "Editor" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
+
+On mobile, Save and Publish sit in a sticky bottom bar and the details panel opens as a slideover. A session expiry mid-edit keeps the draft in sessionStorage and goes to /login?redirect=/article/12/edit. After logging in, the editor restores the draft and shows "Unsaved changes".
+
+## States
+
+### Loading
+
+**Trigger:** GET in flight. Skeletons for the title, content and details.
+
+- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
+- Editor: status "draft", save "saved", loading true
+- Mobile: leading arrow-left button, trailing ellipsis
+
+### Saved
+
+**Trigger:** Just opened or just saved. Save is disabled.
+
+- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
+- Editor: status "draft", save "saved"
+- Mobile: leading arrow-left button, trailing ellipsis
+
+### Unsaved changes
+
+**Trigger:** Any edit. Publish becomes "Save and publish". Leaving asks for confirmation.
+
+- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
+- Editor: status "draft", save "dirty"
+- Mobile: leading arrow-left button, trailing ellipsis
+
+### Saving
+
+**Trigger:** Save, or Ctrl/⌘ S.
+
+- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
+- Editor: status "draft", save "saving"
+- Mobile: leading arrow-left button, trailing ellipsis
+
+### Save failed
+
+**Trigger:** 500 or network failure. The changes are kept and Retry resends them.
+
+- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
+- Editor: status "draft", save "error"
+- Mobile: leading arrow-left button, trailing ellipsis
+
+### Near the limit
+
+**Trigger:** 90% of 10 000 HTML characters.
+
+- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
+- Editor: status "draft", save "dirty", len 9240
+- Mobile: leading arrow-left button, trailing ellipsis
+
+### Too long
+
+**Trigger:** Over 10 000. Save and Publish are disabled until it's shorter.
+
+- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
+- Editor: status "draft", save "dirty", len 10214
+- Mobile: leading arrow-left button, trailing ellipsis
+
+### Preview
+
+**Trigger:** The Preview switch. Shows the title and body in the content scale, the way a public site might.
+
+- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
+- Editor: status "draft", save "saved", preview true
+- Mobile: leading arrow-left button, trailing ellipsis
+
+### Upload: choose
+
+**Trigger:** The image button in the toolbar, or a file dropped on the editor.
+
+- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
+- Modal: **Add an image**
+  - upload state: state "idle"
+  - cancel "Cancel"
+- Editor: status "draft", save "dirty"
+- Mobile: leading arrow-left button, trailing ellipsis
+
+### Upload: in progress
+
+**Trigger:** A valid file is uploading. Closing the dialog cancels the upload.
+
+- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
+- Modal: **Add an image**
+  - upload state: state "uploading"
+  - cancel "Cancel upload"
+- Editor: status "draft", save "dirty"
+- Mobile: leading arrow-left button, trailing ellipsis
+
+### Upload: rejected
+
+**Trigger:** Checked in the browser, so nothing is sent.
+
+- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
+- Modal: **Add an image**
+  - upload state: state "rejected"
+  - cancel "Cancel"
+  - confirm "Choose another file"
+- Editor: status "draft", save "dirty"
+- Mobile: leading arrow-left button, trailing ellipsis
+
+### Upload: inserted
+
+**Trigger:** 201: the image goes in at the cursor, and the article now has unsaved changes.
+
+- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
+- Toast (success, circle-check): **Image added** "Save to keep it in the article."
+- Editor: status "draft", save "dirty", image true
+- Mobile: leading arrow-left button, trailing ellipsis
+
+### Publishing
+
+**Trigger:** "Save and publish": the PATCH body, then the publish request.
+
+- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
+- Editor: status "draft", save "saving", pending "Saving and publishing…"
+- Mobile: leading arrow-left button, trailing ellipsis
+
+### Published
+
+**Trigger:** 200: the badge flips, Unpublish is offered and a toast confirms.
+
+- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
+- Toast (success, circle-check): **Article published** ""How we price a bathroom renovation" is now online."
+- Editor: status "online", save "saved"
+- Mobile: leading arrow-left button, trailing ellipsis
+
+### Unpublishing
+
+**Trigger:** Unpublish doesn't save pending edits.
+
+- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
+- Editor: status "online", save "saved", pending "Unpublishing…"
+- Mobile: leading arrow-left button, trailing ellipsis
+
+### Delete: confirm
+
+**Trigger:** Delete… from the overflow menu. After a 204, it goes to /article with the "Article deleted" toast.
+
+- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
+- Modal: **Delete this article?**
+  - text ""How we price a bathroom renovation" and its 3 images will be deleted. This can't be undone."
+  - cancel "Cancel"
+  - confirm "Delete article" (danger)
+- Editor: status "draft", save "saved"
+- Mobile: leading arrow-left button, trailing ellipsis
+
+### Leave with unsaved changes
+
+**Trigger:** Back, a nav link or closing the tab.
+
+- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
+- Modal: **Leave without saving?**
+  - text "Your changes to "How we price a bathroom renovation" haven't been saved."
+  - cancel "Discard changes"
+  - confirm "Keep editing"
+- Editor: status "draft", save "dirty"
+- Mobile: leading arrow-left button, trailing ellipsis
+
+### Offline
+
+**Trigger:** The connection dropped. Writing continues, and Save and Publish wait.
+
+- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
+- Editor: status "draft", save "offline"
+- offline: true
+- Mobile: leading arrow-left button, trailing ellipsis
+
+### Not found (404)
+
+**Trigger:** Unknown id, or the article was deleted elsewhere.
+
+- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
+- Editor: status "draft", save "saved", notfound true
+- Mobile: leading arrow-left button, trailing ellipsis

docs/design/screens/forgot-password.md

@@ -0,0 +1,68 @@
+# Forgot password
+
+- **Route:** `/register/reset/request`
+- **API:** POST /v1/auth/password-reset
+- **Visual reference:** `source/RenewCMS Screens Auth.dc.html`, group "Forgot password" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
+
+The sent state reads the same whether or not the email exists, so the page doesn't reveal which emails have accounts.
+
+## States
+
+### Default
+
+**Trigger:** From "Forgot password?" on log in.
+
+- Heading: **Reset your password**
+- Description: "Enter the email for your account and we'll send you a link to choose a new password."
+- Field `Email`: placeholder "you@example.com"
+- Submit button: "Send reset link"
+- Below the card: [Back to log in]
+
+### Validation error
+
+**Trigger:** Invalid email on submit. Nothing is sent.
+
+- Heading: **Reset your password**
+- Description: "Enter the email for your account and we'll send you a link to choose a new password."
+- Field `Email`: placeholder "you@example.com"; value "marta@renew"; **error "Enter a full email address, like name@example.com."**
+- Submit button: "Send reset link"
+- Below the card: [Back to log in]
+
+### Submitting
+
+**Trigger:** Request in flight.
+
+- Heading: **Reset your password**
+- Description: "Enter the email for your account and we'll send you a link to choose a new password."
+- Field `Email`: placeholder "you@example.com"; value "marta@renew.example"
+- Submit button: "Sending…", loading
+- Below the card: [Back to log in]
+
+### Sent
+
+**Trigger:** Any 200, whether or not the account exists.
+
+- ResultPanel (success, mail-check): **Check your email**; text "If an account exists for that email, a password reset link has been sent."; note "The link expires in 1 hour."; actions "Back to log in" (secondary)
+
+### Too many attempts (429)
+
+**Trigger:** Rate limit with Retry-After.
+
+- Relied on an API marked pending in the design; that API now exists.
+- Alert (info, timer): **Too many requests** "Wait a moment before asking for another link."
+- Heading: **Reset your password**
+- Description: "Enter the email for your account and we'll send you a link to choose a new password."
+- Field `Email`: placeholder "you@example.com"; value "marta@renew.example"
+- Submit button: "Try again in 0:58", disabled
+- Below the card: [Back to log in]
+
+### Server error
+
+**Trigger:** 500 or no response.
+
+- Alert (error, circle-x): **Couldn't send the link** "Check your connection and try again."
+- Heading: **Reset your password**
+- Description: "Enter the email for your account and we'll send you a link to choose a new password."
+- Field `Email`: placeholder "you@example.com"; value "marta@renew.example"
+- Submit button: "Send reset link"
+- Below the card: [Back to log in]

docs/design/screens/global.md

@@ -0,0 +1,39 @@
+# Global states
+
+- **Route:** `any route`
+- **API:** 
+- **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "Global" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
+
+A 401 on any back-office call redirects to /login?redirect=<path>&reason=expired (see "Session expired" on the auth board). A 403 from an unverified account redirects to /register/pending. A 429 appears only on log in and password reset. Toasts sit bottom right on desktop and bottom center on mobile, at most 3 at once. Success and info last 5 s; errors stay until dismissed.
+
+## States
+
+### 404 inside the shell
+
+**Trigger:** An unknown route while logged in. Logged out, the same content appears inside AuthShell.
+
+- Breadcrumbs: Not found (mobile title "Not found")
+- err: {"code":"404","title":"Page not found","text":"The link may be mistyped, or the page may have moved.","primary":"Go to Home","secondary":"All articles"}
+
+### Generic error
+
+**Trigger:** An unexpected error while rendering a route.
+
+- Breadcrumbs: Home (mobile title "Home")
+- err: {"code":"Error","title":"Something went wrong","text":"This page couldn't load. Your saved work is safe. Try again, and if it keeps happening, restart the RenewCMS server.","primary":"Try again","secondary":"Go to Home"}
+
+### Offline banner
+
+**Trigger:** navigator.onLine is false. The banner is shown on every back-office page.
+
+- Breadcrumbs: Articles (mobile title "Articles")
+- offline: true
+
+### Toast stack
+
+**Trigger:** Three at most, newest at the bottom. A fourth pushes out the oldest non-error toast.
+
+- Breadcrumbs: Articles (mobile title "Articles")
+- Toast (success, circle-check): **Article published** ""Winter checklist for timber windows" is now online."
+- Toast (info, info): **That article no longer exists** "It was deleted somewhere else, so we removed it from the list."
+- Toast (error, circle-x): **Couldn't unpublish** "The server didn't respond. Nothing changed." with action "Retry"

docs/design/screens/home.md

@@ -0,0 +1,42 @@
+# Home
+
+- **Route:** `/home`
+- **API:** GET /v1/article/
+- **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "Home" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
+
+The counts come from the list, so there's no separate endpoint. The five most recently updated articles link to the editor.
+
+## States
+
+### Default
+
+**Trigger:** The articles loaded.
+
+- Breadcrumbs: Home (mobile title "Home")
+- Subtitle: "Here's where things stand on your site."
+- Stats: 6 articles, 4 online, 2 drafts
+- Recent: the 5 most recently updated articles, with status
+
+### Loading
+
+**Trigger:** The list request is in flight. Skeletons appear after 150 ms.
+
+- Breadcrumbs: Home (mobile title "Home")
+- Subtitle: "Here's where things stand on your site."
+- Stats and recent list: skeletons
+
+### Empty, first run
+
+**Trigger:** Zero articles: a single call to action, and no stats.
+
+- Breadcrumbs: Home (mobile title "Home")
+- Subtitle: "Welcome to RenewCMS."
+- First-run empty state instead of stats and recent list
+
+### Error
+
+**Trigger:** A 500 or network failure on the list request.
+
+- Breadcrumbs: Home (mobile title "Home")
+- Subtitle: "Here's where things stand on your site."
+- Error state for the list request

docs/design/screens/integration.md

@@ -0,0 +1,22 @@
+# Connect your website
+
+- **Route:** `/integration`
+- **API:** none (static)
+- **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "Integration" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
+
+Written for a developer. The base URL is window.location.origin.
+
+## States
+
+### Default
+
+**Trigger:** Opened from the sidebar or the Home card.
+
+- Breadcrumbs: Integration (mobile title "Integration")
+
+### Copied
+
+**Trigger:** The base URL was copied. The button reads "Copied" for 2 s and this is announced.
+
+- Breadcrumbs: Integration (mobile title "Integration")
+- copied: true

docs/design/screens/log-in.md

@@ -0,0 +1,107 @@
+# Log in
+
+- **Route:** `/login`
+- **API:** GET /v1/auth/registration (pending) · POST /v1/auth/login
+- **Visual reference:** `source/RenewCMS Screens Auth.dc.html`, group "Log in" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
+
+After logging in, you go back to the page you originally asked for (?redirect=), or to /home. An unverified account goes to /register/pending. "Create the owner account" appears only when registration is open.
+
+## States
+
+### Default
+
+**Trigger:** Registration is closed, which is the usual case.
+
+- Heading: **Log in**
+- Description: "Welcome back. Log in to manage your articles."
+- Field `Username`: placeholder "Your username"
+- Field `Password`: password with show/hide; link "Forgot password?"
+- Submit button: "Log in"
+
+### Fresh install
+
+**Trigger:** GET /v1/auth/registration returns { open: true }.
+
+- Relied on an API marked pending in the design; that API now exists.
+- Heading: **Log in**
+- Description: "Welcome back. Log in to manage your articles."
+- Field `Username`: placeholder "Your username"
+- Field `Password`: password with show/hide; link "Forgot password?"
+- Submit button: "Log in"
+- Footer: First time here? [Create the owner account]
+
+### Validation errors
+
+**Trigger:** Submit with a short username and an empty password. Nothing is sent.
+
+- Heading: **Log in**
+- Description: "Welcome back. Log in to manage your articles."
+- Field `Username`: placeholder "Your username"; value "ma"; **error "Use at least 3 characters."**
+- Field `Password`: password with show/hide; link "Forgot password?"; **error "Enter your password."**
+- Submit button: "Log in"
+
+### Submitting
+
+**Trigger:** The request is in flight. Fields and button are disabled.
+
+- Heading: **Log in**
+- Description: "Welcome back. Log in to manage your articles."
+- Field `Username`: placeholder "Your username"; value "marta"
+- Field `Password`: value "limewash2026"; password with show/hide; link "Forgot password?"
+- Submit button: "Logging in…", loading
+
+### Wrong credentials (403)
+
+**Trigger:** The API doesn't say which field is wrong, so neither does the message. The password is cleared and gets focus.
+
+- Alert (error, circle-x): **That username and password don't match** "Check both and try again. Passwords are case-sensitive."
+- Heading: **Log in**
+- Description: "Welcome back. Log in to manage your articles."
+- Field `Username`: placeholder "Your username"; value "marta"
+- Field `Password`: password with show/hide; focused; link "Forgot password?"
+- Submit button: "Log in"
+
+### Too many attempts (429)
+
+**Trigger:** Retry-After is counted down. The button re-enables at zero.
+
+- Relied on an API marked pending in the design; that API now exists.
+- Alert (info, timer): **Too many attempts** "For your security, wait a moment before trying again."
+- Heading: **Log in**
+- Description: "Welcome back. Log in to manage your articles."
+- Field `Username`: placeholder "Your username"; value "marta"
+- Field `Password`: value "limewash"; password with show/hide; link "Forgot password?"
+- Submit button: "Try again in 0:42", disabled
+
+### Session expired
+
+**Trigger:** Redirected from a 401 with ?redirect=/article/12/edit&reason=expired. Unsaved edits are kept in the browser.
+
+- Alert (info, clock): **Your session expired** "Log in again to pick up where you left off. Unsaved changes are kept on this device."
+- Heading: **Log in**
+- Description: "Welcome back. Log in to manage your articles."
+- Field `Username`: placeholder "Your username"; value "marta"
+- Field `Password`: password with show/hide; focused; link "Forgot password?"
+- Submit button: "Log in"
+
+### Password changed
+
+**Trigger:** Arrived from a successful reset with ?reason=password-changed.
+
+- Alert (success, circle-check): **Password changed** "Log in with your new password."
+- Heading: **Log in**
+- Description: "Welcome back. Log in to manage your articles."
+- Field `Username`: placeholder "Your username"
+- Field `Password`: password with show/hide; link "Forgot password?"
+- Submit button: "Log in"
+
+### Server or network error
+
+**Trigger:** A 500 or no response. The fields keep their values.
+
+- Alert (error, circle-x): **Couldn't reach RenewCMS** "Check your connection and try again."
+- Heading: **Log in**
+- Description: "Welcome back. Log in to manage your articles."
+- Field `Username`: placeholder "Your username"; value "marta"
+- Field `Password`: value "limewash2026"; password with show/hide; link "Forgot password?"
+- Submit button: "Log in"

docs/design/screens/new-article.md

@@ -0,0 +1,71 @@
+# New article
+
+- **Route:** `modal from anywhere · /article/new`
+- **API:** POST /v1/article/
+- **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "New article" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
+
+Recommendation: a modal. It needs two fields, and keeping the page underneath means cancelling costs nothing. /article/new opens the same modal over the article list, so it can be linked to and the back button closes it. A successful create always makes a draft and goes to the editor.
+
+## States
+
+### Default
+
+**Trigger:** "New article" from Home, Articles or the empty state.
+
+- Breadcrumbs: Articles (mobile title "Articles")
+- Modal: **New article**
+  - text "It's saved as a draft. Titles can't be changed later, so check it now."
+  - field `Title`: placeholder "e.g. Choosing tiles for a small bathroom"; focused; counter "0 / 200"; help "3 to 200 characters."
+  - field `First paragraph`: placeholder "Start writing. You'll continue in the editor."; textarea; help "You can format it and add images in the editor."
+  - cancel "Cancel"
+  - confirm "Create draft"
+
+### Validation
+
+**Trigger:** On submit or blur. Nothing is sent.
+
+- Breadcrumbs: Articles (mobile title "Articles")
+- Modal: **New article**
+  - text "It's saved as a draft. Titles can't be changed later, so check it now."
+  - field `Title`: value "Ti"; counter "2 / 200" in error; **error "Use at least 3 characters."**
+  - field `First paragraph`: textarea; **error "Add a first paragraph. It can be a single sentence."**
+  - cancel "Cancel"
+  - confirm "Create draft"
+
+### Submitting
+
+**Trigger:** Request in flight. Fields are disabled and the dialog can't be dismissed.
+
+- Breadcrumbs: Articles (mobile title "Articles")
+- Modal: **New article**
+  - text "It's saved as a draft. Titles can't be changed later, so check it now."
+  - field `Title`: value "Choosing tiles for a small bathroom"; counter "35 / 200"
+  - field `First paragraph`: value "Small rooms show every grout line, so we start with the floor."; textarea
+  - cancel "Cancel"
+  - confirm "Creating…", loading, not dismissible
+
+### Title rejected (400)
+
+**Trigger:** A server 400 that got past the browser checks. The raw error isn't shown.
+
+- Breadcrumbs: Articles (mobile title "Articles")
+- Modal: **New article**
+  - text "It's saved as a draft. Titles can't be changed later, so check it now."
+  - field `Title`: value "Choosing tiles for a small bathroom"; counter "35 / 200"; **error "Check this title and try again."**
+  - field `First paragraph`: value "Small rooms show every grout line, so we start with the floor."; textarea
+  - Alert: "Something in the form isn't valid. Check the highlighted fields."
+  - cancel "Cancel"
+  - confirm "Create draft"
+
+### Error
+
+**Trigger:** 500 or network failure.
+
+- Breadcrumbs: Articles (mobile title "Articles")
+- Modal: **New article**
+  - text "It's saved as a draft. Titles can't be changed later, so check it now."
+  - field `Title`: value "Choosing tiles for a small bathroom"; counter "35 / 200"
+  - field `First paragraph`: value "Small rooms show every grout line, so we start with the floor."; textarea
+  - Alert: "Couldn't create the article. Your text is still here. Try again in a moment."
+  - cancel "Cancel"
+  - confirm "Create draft"

docs/design/screens/pending.md

@@ -0,0 +1,61 @@
+# Check your email
+
+- **Route:** `/register/pending`
+- **API:** DELETE /v1/auth/register · POST /v1/auth/logout
+- **Visual reference:** `source/RenewCMS Screens Auth.dc.html`, group "Pending" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
+
+Any back-office route visited by an unverified account lands here. There's no way to resend the email because the API doesn't offer one, so the note explains the way out.
+
+## States
+
+### Default
+
+**Trigger:** Straight after registering, when the email is known from the form.
+
+- ResultPanel (success, mail-check): **Check your email**; text "We sent a verification link to marta@renew.example. It expires in 2 hours."; note "Opened it on another device? That works too; you'll log in there first. Can't find it? Check your spam folder. If the link has expired, cancel your registration and start again."; actions "Log out" (secondary), "Cancel registration" (secondary)
+
+### Email unknown
+
+**Trigger:** Arrived after logging in as an unverified user.
+
+- ResultPanel (success, mail-check): **Check your email**; text "We sent a verification link to the email you registered with. It expires in 2 hours."; note "Opened it on another device? That works too; you'll log in there first. Can't find it? Check your spam folder. If the link has expired, cancel your registration and start again."; actions "Log out" (secondary), "Cancel registration" (secondary)
+
+### Confirm cancel
+
+**Trigger:** "Cancel registration" opens the destructive ConfirmDialog.
+
+- ResultPanel (success, mail-check): **Check your email**; text "We sent a verification link to marta@renew.example. It expires in 2 hours."; note "Opened it on another device? That works too; you'll log in there first. Can't find it? Check your spam folder. If the link has expired, cancel your registration and start again."; actions "Log out" (secondary), "Cancel registration" (secondary)
+- ConfirmDialog: **Cancel your registration?**
+  - text "Your account will be deleted. You can register again with the same or a different email."
+  - cancel "Keep my account"
+  - confirm "Cancel registration"
+
+### Cancelling
+
+**Trigger:** DELETE in flight. The dialog can't be dismissed.
+
+- ResultPanel (success, mail-check): **Check your email**; text "We sent a verification link to marta@renew.example. It expires in 2 hours."; note "Opened it on another device? That works too; you'll log in there first. Can't find it? Check your spam folder. If the link has expired, cancel your registration and start again."; actions "Log out" (secondary), "Cancel registration" (secondary)
+- ConfirmDialog: **Cancel your registration?**
+  - text "Your account will be deleted. You can register again with the same or a different email."
+  - cancel "Keep my account"
+  - confirm "Cancelling…"
+
+### Cancelled
+
+**Trigger:** 200 → /register, with a toast.
+
+- Heading: **Create the owner account**
+- Description: "This creates the single admin account for this site. Once it's verified, registration closes."
+- Field `Username`: placeholder "e.g. marta"; counter "0 / 20"; help "Letters and numbers, 3 to 20 characters. You'll use it to log in."
+- Field `Email`: placeholder "you@example.com"; help "We'll send a verification link here."
+- Field `Password`: password with show/hide; checklist "At least 8 characters" (unmet)
+- Submit button: "Create account"
+- Footer: Already set up? [Log in]
+- Toast (circle-check): **Registration cancelled** "You can create the owner account again."
+
+### Already verified (403)
+
+**Trigger:** Verified on another device. Goes to /home; shown here as the toast over the destination.
+
+- ResultPanel (success, shield-check): **You're verified**; text "Taking you to your dashboard…"
+- Toast (info): **Your account is already verified** "There's nothing to cancel."

docs/design/screens/register.md

@@ -0,0 +1,76 @@
+# Create the owner account
+
+- **Route:** `/register`
+- **API:** POST /v1/auth/register
+- **Visual reference:** `source/RenewCMS Screens Auth.dc.html`, group "Register" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
+
+Seen once, on a fresh install. After registering, the new user is logged in but not yet verified, and goes to /register/pending.
+
+## States
+
+### Default
+
+**Trigger:** Registration is open.
+
+- Heading: **Create the owner account**
+- Description: "This creates the single admin account for this site. Once it's verified, registration closes."
+- Field `Username`: placeholder "e.g. marta"; counter "0 / 20"; help "Letters and numbers, 3 to 20 characters. You'll use it to log in."
+- Field `Email`: placeholder "you@example.com"; help "We'll send a verification link here."
+- Field `Password`: password with show/hide; checklist "At least 8 characters" (unmet)
+- Submit button: "Create account"
+- Footer: Already set up? [Log in]
+
+### Validation errors
+
+**Trigger:** Checked on blur and on submit, using the same rules as the API.
+
+- Heading: **Create the owner account**
+- Description: "This creates the single admin account for this site. Once it's verified, registration closes."
+- Field `Username`: placeholder "e.g. marta"; value "ma"; counter "2 / 20" in error; **error "Use 3 to 20 characters."**
+- Field `Email`: placeholder "you@example.com"; value "marta@renew"; **error "Enter a full email address, like name@example.com."**
+- Field `Password`: value "lime"; password with show/hide; checklist "At least 8 characters" (err)
+- Submit button: "Create account"
+- Footer: Already set up? [Log in]
+
+### Filled, valid
+
+**Trigger:** Every rule is met and the checklist item turns green.
+
+- Heading: **Create the owner account**
+- Description: "This creates the single admin account for this site. Once it's verified, registration closes."
+- Field `Username`: placeholder "e.g. marta"; value "marta"; counter "5 / 20"; help "Letters and numbers, 3 to 20 characters. You'll use it to log in."
+- Field `Email`: placeholder "you@example.com"; value "marta@renew.example"; help "We'll send a verification link here."
+- Field `Password`: value "limewash2026"; password with show/hide; password shown; checklist "At least 8 characters" (met)
+- Submit button: "Create account"
+- Footer: Already set up? [Log in]
+
+### Submitting
+
+**Trigger:** Fields and button are disabled.
+
+- Heading: **Create the owner account**
+- Description: "This creates the single admin account for this site. Once it's verified, registration closes."
+- Field `Username`: placeholder "e.g. marta"; value "marta"; counter "5 / 20"; help "Letters and numbers, 3 to 20 characters. You'll use it to log in."
+- Field `Email`: placeholder "you@example.com"; value "marta@renew.example"; help "We'll send a verification link here."
+- Field `Password`: value "limewash2026"; password with show/hide; checklist "At least 8 characters" (met)
+- Submit button: "Creating account…", loading
+- Footer: Already set up? [Log in]
+
+### Registration closed (403)
+
+**Trigger:** Someone already verified an owner account. The form is replaced.
+
+- ResultPanel (info, user-x): **This site already has an owner**; text "Log in instead."; actions "Go to log in" (primary)
+
+### Server error
+
+**Trigger:** A 500 or no response. The values are kept.
+
+- Alert (error, circle-x): **Couldn't create the account** "Something went wrong on the server. Try again in a moment."
+- Heading: **Create the owner account**
+- Description: "This creates the single admin account for this site. Once it's verified, registration closes."
+- Field `Username`: placeholder "e.g. marta"; value "marta"; counter "5 / 20"; help "Letters and numbers, 3 to 20 characters. You'll use it to log in."
+- Field `Email`: placeholder "you@example.com"; value "marta@renew.example"; help "We'll send a verification link here."
+- Field `Password`: value "limewash2026"; password with show/hide; checklist "At least 8 characters" (met)
+- Submit button: "Create account"
+- Footer: Already set up? [Log in]

docs/design/screens/reset-password.md

@@ -0,0 +1,76 @@
+# Choose a new password
+
+- **Route:** `/register/reset/validate?c=CODE&email=EMAIL`
+- **API:** POST /v1/auth/password-reset/confirm
+- **Visual reference:** `source/RenewCMS Screens Auth.dc.html`, group "Reset password" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
+
+Opened from the reset email. The email comes from the URL and is read-only. The confirm field is checked only in the browser.
+
+## States
+
+### Default
+
+**Trigger:** Both parameters are present.
+
+- Heading: **Choose a new password**
+- Description: "Pick something you haven't used here before. You'll log in with it next."
+- Field `Email`: placeholder "you@example.com"; value "marta@renew.example"; read-only; help "From your reset link."
+- Field `New password`: password with show/hide; checklist "At least 8 characters" (unmet)
+- Field `Confirm new password`: password with show/hide; checklist "Passwords match" (unmet)
+- Submit button: "Change password"
+
+### Too short
+
+**Trigger:** On submit, with fewer than 8 characters.
+
+- Heading: **Choose a new password**
+- Description: "Pick something you haven't used here before. You'll log in with it next."
+- Field `Email`: placeholder "you@example.com"; value "marta@renew.example"; read-only; help "From your reset link."
+- Field `New password`: value "lime"; password with show/hide; checklist "At least 8 characters" (err)
+- Field `Confirm new password`: value "lime"; password with show/hide; checklist "Passwords match" (met)
+- Submit button: "Change password"
+
+### Mismatch
+
+**Trigger:** On blur of the confirm field, or on submit.
+
+- Heading: **Choose a new password**
+- Description: "Pick something you haven't used here before. You'll log in with it next."
+- Field `Email`: placeholder "you@example.com"; value "marta@renew.example"; read-only; help "From your reset link."
+- Field `New password`: value "limewash2026"; password with show/hide; checklist "At least 8 characters" (met)
+- Field `Confirm new password`: value "limewash2025"; password with show/hide; **error "The passwords don't match."**; checklist "Passwords match" (err)
+- Submit button: "Change password"
+
+### Submitting
+
+**Trigger:** Request in flight.
+
+- Heading: **Choose a new password**
+- Description: "Pick something you haven't used here before. You'll log in with it next."
+- Field `Email`: placeholder "you@example.com"; value "marta@renew.example"; read-only; help "From your reset link."
+- Field `New password`: value "limewash2026"; password with show/hide; checklist "At least 8 characters" (met)
+- Field `Confirm new password`: value "limewash2026"; password with show/hide; checklist "Passwords match" (met)
+- Submit button: "Changing password…", loading
+
+### Success
+
+**Trigger:** 200 → /login?reason=password-changed.
+
+- Alert (success, circle-check): **Password changed** "Log in with your new password."
+- Heading: **Log in**
+- Description: "Welcome back. Log in to manage your articles."
+- Field `Username`: placeholder "Your username"
+- Field `Password`: password with show/hide; link "Forgot password?"
+- Submit button: "Log in"
+
+### Invalid or expired (403)
+
+**Trigger:** The code is wrong, used, or older than 1 hour.
+
+- ResultPanel (error, link-2-off): **This reset link has expired**; text "Reset links work once, for 1 hour. Request a new one and use it within the hour."; actions "Request a new link" (primary), "Back to log in" (secondary)
+
+### Missing parameters
+
+**Trigger:** The link has no c or no email. No request is made.
+
+- ResultPanel (error, link-2-off): **This link is incomplete**; text "Part of the reset link is missing. Open it from your email again, or request a new one."; actions "Request a new link" (primary)

docs/design/screens/verify.md

@@ -0,0 +1,50 @@
+# Verify account
+
+- **Route:** `/register/validate?c=CODE`
+- **API:** POST /v1/auth/verify
+- **Visual reference:** `source/RenewCMS Screens Auth.dc.html`, group "Verify" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
+
+Opened from the verification email, and submits automatically on load. This is the only full-card spinner in the product.
+
+## States
+
+### Verifying
+
+**Trigger:** On load, with a code in the URL.
+
+- Full-card spinner: "Verifying your account…"
+
+### Success
+
+**Trigger:** 200 → /home after 800 ms, with a toast.
+
+- ResultPanel (success, shield-check): **Your account is verified**; text "Taking you to your dashboard…"
+- Toast (circle-check): **Your account is verified** "Welcome to RenewCMS."
+
+### Invalid or expired (403)
+
+**Trigger:** The code is wrong, used, or older than 2 hours.
+
+- ResultPanel (error, link-2-off): **This verification link doesn't work**; text "It may have expired (links last 2 hours) or already been used."; note "Cancel your registration and start over to get a new link."; actions "Cancel registration and start over" (primary), "Log out" (secondary)
+
+### No session (401)
+
+**Trigger:** Opened in another browser or device. Log in inline, then verification retries automatically with the same code.
+
+- Heading: **Log in to finish verifying**
+- Description: "You opened this link somewhere you're not logged in. Log in here and we'll verify your account right after."
+- Field `Username`: placeholder "Your username"
+- Field `Password`: password with show/hide
+- Submit button: "Log in and verify"
+
+### No session, retrying
+
+**Trigger:** Logged in inline. Now verifying.
+
+- Full-card spinner: "Verifying your account…"
+
+### Missing code
+
+**Trigger:** The link has no ?c= parameter. No request is made.
+
+- ResultPanel (error, link-2-off): **This link is incomplete**; text "The verification code is missing. Open the link from your email again, or copy the full address into your browser."; actions "Go to log in" (secondary)