R1 — Foundations and front door (v0.7.0)

The first release of Phase R (70-redesign-overview.md). It lays the deck's visual foundation under the whole app and rebuilds everything a person sees before they reach a console: sign in, forgot password, join, change password, the four system pages and the splash. It also adds the one maintenance mechanism the programme uses. R0's groundwork (deck import, docs rewrite, gap register) rides to production in the same version.

Nothing inside a console is rebuilt. The old teacher and student consoles take the new palette, font and focus ring and keep their layout and geometry, because the primitives are additive (ordering rule 1, D7). Screens are compared with docs/design/deck/Quizzivy Sign in.dc.html (#login, #forgot, #join, #joined, #change), Quizzivy System pages.dc.html (#404, #403, #error, #maintenance) and Quizzivy Splash.dc.html (#loading, #skeleton, #slow, #offline, #update, #expired). Design gaps are cited by DG id from docs/design/gaps.md.

Deliverable: deck tokens (light and dark), Be Vietnam Pro, motion, icons and additive primitives; the rebuilt front door, system pages and splash; maintenance windows end to end (operator command, public status, 503 gate, deadline extensions a running attempt picks up). Exit criteria:

every front-door, system and splash screen matches the deck at 360, 768, 1024, 1280 and 1440, light and dark, measured in the browser;
every old /admin and /app route keeps its layout at 1280 and 360, in light, with the new palette and font;
a maintenance window rehearsed locally end to end: scheduled with cmd/maintenance, the SPA shows the maintenance page, an attempt in progress is extended and its timer shows the new deadline after the window, a start that would overlap is refused;
every CI step green locally and in CI, E2E chromium and live green;
released to production as v0.7.0.

Decisions taken in this file, worth a second look.

Deck geometry is scoped by data-scale="deck", not by call site. Colours, font and the focus ring change globally. Control heights, paddings and the sm/md/lg radii that differ from today apply only inside an element carrying data-scale="deck" (Tailwind v4's in-data-* variant, and --radius redefined in that scope). Rebuilt surfaces set it on their root: the front door and system pages in R1, each console as it is rebuilt. This is what "additive" means in practice: an old screen cannot shift because no class it renders changes meaning. R5 deletes the scope and makes the deck geometry the default (the "primitive defaults flip").
No theme control ships in R1. The preference (light | dark | system, default light, the deck's startTheme) and the boot script exist, and the front door honours them, but the only surfaces the deck gives a toggle are the console top bars, account menus and Settings › Appearance, all rebuilt in R3–R5. Old consoles force light while mounted, so a dark preference set later in the student app (R3) cannot paint the old teacher console half dark (D7). Dark is verified in R1 through the test harness.
Deck token names are kept verbatim on :root, so deck CSS diffs against ours. The lime is brand in utilities (bg-brand, text-brand-ink) because shadcn's accent already means the hover surface. The legacy shadcn and semantic names (destructive-ink, *-foreground) stay as aliases until R5 rather than sweeping old screens now.
Three tokens go beyond the deck, for accessibility (DG-30, DG-31): --focus (the focus ring, set to --muted-fg: 5.4:1 on white, 7.1:1 on the dark background), a darker --input border (#8a9395 light, 3.1:1; #5d6769 dark, 3.2:1) and --danger-solid (oklch(0.55 0.2 27), about 5.4:1 under white text) for destructive buttons. The deck's --ring (2.6:1) and --border (1.25:1) stay for what the deck uses them for. The token test measures all three, so a design answer that changes them fails loudly rather than silently.
One maintenance mechanism, written only by the operator. app.maintenance_windows is created by a migration and written only through cmd/maintenance under MAINTENANCE_DATABASE_URL; the app role gets SELECT and nothing else. There is no MAINTENANCE_MODE environment switch and no admin endpoint: the deck draws no control (DG-42), and a table the API cannot write cannot be turned on by a compromised session.
Extensions are applied when the window is scheduled, in the same statement that inserts it, audited as System (actor_user_id NULL). Every in-progress attempt whose deadline falls after the window's start gains the window's length; every assignment that closes inside the window gains the same. Doing it at scheduling time needs no timer in the API and cannot be skipped by a process that was asleep at the start. Cancelling or ending a window early keeps the extensions: giving time back is harmless, taking it back mid-test is not.
No new attempt may overlap a window. Starting one whose deadline would pass a scheduled window's start answers 409 MAINTENANCE_SCHEDULED; resuming is never refused. The start and the scheduling serialise on one advisory lock, following the LockForDraftUse / LockForVersionUse precedent, so no attempt slips between them.
The 503 gate exempts no role and covers the integrity beacon. An admin exemption needs the principal, which exists only after auth, and a role model R2 replaces; the operator ends a window early instead. Events the beacon would send during a window are dropped, and the client pauses integrity capture while the maintenance or session-expired overlay shows, so a student is never flagged for looking away from a page that told them to wait.
A running attempt learns a moved deadline. Today the client takes deadlineAt only from the session payload, so an extension (a teacher's Extend, or maintenance) reaches an open tab only after a reload, and its local timer submits early. R1 returns deadlineAt from every autosave and refuses a timer_expired submit that arrives more than five seconds before the server's deadline (409 DEADLINE_NOT_REACHED); the store adopts the server's deadline from either. Without this, maintenance extensions would be granted on the server and lost in the browser.
Unavailable is not signed out. A refresh that fails because the network is down or the API answers 503 no longer signs the user out; only a refused refresh does. Today an offline cold load lands on /login, and maintenance would do the same to every open tab.
App states are overlays over a mounted route, not routes. Maintenance, session expired and update render above the current page (made inert), so an attempt stays mounted beneath with its local draft. The deck's "Check again" reloads the page; ours re-reads the status and closes the overlay, for the same reason. The update prompt waits for the next navigation and never appears on the take-test route.
Joined is a state of /join/:code, not a route. 70-redesign-overview.md §5 lists the front-door routes and has no /joined; the success step lives in the join route's location state (it survives a reload). /join/:code/confirm redirects, so printed QR codes and old links keep working.
Password rules are a schema constraint. newPassword gains pattern: '[\p{N}\p{P}\p{S}]' (a number, punctuation or symbol character; a Vietnamese letter is a letter), enforced once by httpx.ValidateRequests. "Different from the temporary password" becomes PASSWORD_UNCHANGED, applied to every change (for an ordinary change it is a comparison with the verified current password). Existing passwords are never re-validated.
Organisation details come from build-time config. The org name (brand panel, system-page caption) and the front-desk phone and hours (Forgot password) are VITE_ORG_* values, each line hidden when unset (DG-41). The build values stay after R5: R5's Organization settings take precedence on the front door, which falls back to these values when a setting is empty or the API is unreachable, and they are the Landing's contact source (R11). R11 adds VITE_ORG_EMAIL and VITE_ORG_ADDRESS (T-R11.4b); no release removes them.
The join page sends at most one preview per distinct complete code, as today's confirm page does. The re-budget of the join and login limits for a class behind one school NAT stays in R2, as the approved plan places it; R1 does not raise request volume, and a unit test pins that.
The §6 alphabet string is authoritative. ABCDEFGHJKLMNPQRSTUVWXYZ23456789 contains L; the spec's "(no 1/I/L)" and DG-02's "no … L" are wrong, and both the client (features/join/code.ts) and the server (classes/domain/joincode.go) use the string. The R1 docs task corrects the prose.
The read side lives in a new availability module: the window query, the status endpoint and the start guard. R5's organization module may absorb it; nothing else depends on the name.

T-R1.1 — Tokens and the token test

Depends on: T-R0.1 Touches: web/src/index.css, web/tests/units/styles/tokens.test.ts, web/tests/units/styles/no-raw-colours.test.ts (new) Size: M Done when:

T-R1.2 — Be Vietnam Pro, self-hosted

Depends on: T-R1.1 Touches: web/package.json, web/pnpm-lock.yaml, web/src/index.css, web/tests/integration/fonts.test.ts (new) Size: S Done when:

New dependency @fontsource/be-vietnam-pro, reason stated in the PR: the deck mandates the family, font-src 'self' in web/public/_headers forbids Google Fonts, and the package pins versioned OFL files with unicode-range subsets. Vendoring woff2 files by hand was the alternative considered.
Imported: latin and vietnamese subsets × 400/500/600/700, font-display: swap; latin-ext left out.
--font-sans: "Be Vietnam Pro", ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; --font-mono: ui-monospace, SFMono-Regular, Menlo, monospace; Inter removed.
fonts.test.ts (real build): the CSS references fonts only under /assets/*.woff2, the Vietnamese subset is emitted, and no fonts.googleapis.com or fonts.gstatic.com string appears anywhere in dist/.
_headers CSP unchanged; checked in Chromium that "Đặng Thu Hà · Nguyễn Gia Bảo · Ươ" renders in Be Vietnam Pro with no fallback glyph (DevTools "Rendered fonts", noted in PR).

T-R1.3 — Theme preference and the boot script

Depends on: T-R1.1 Touches: web/index.html, web/public/boot.js (new), web/public/_headers, web/public/brand/quizzivy-mark-on-dark.svg (new, copied from the deck), web/src/lib/theme.ts (new), web/src/components/shared/Brand.tsx, web/src/layouts/{AdminLayout,StudentLayout,FocusLayout}.tsx, web/tests/units/lib/theme.test.ts (new), web/tests/units/i18n/default-locale.test.ts (new), web/tests/e2e/theme.spec.ts (new) Size: M Done when:

The preference is light | dark | system in localStorage['quizzivy.theme']; absent or invalid means light. Every storage access is in try/catch and the app renders without storage (70 §6 "Browser storage").
Vietnamese is the default language (DG-20): an absent or invalid quizzivy.locale, or storage that throws, resolves to vi in both boot.js (html.lang="vi") and lib/i18n (DEFAULT_LOCALE), never to the deck's English default. web/tests/units/i18n/default-locale.test.ts (new) covers the three cases for both.
web/public/boot.js is an external classic script (CSP script-src 'self' allows no inline script) loaded blocking in <head>. It reads quizzivy.theme and quizzivy.locale, sets html.dark, html.style.colorScheme and html.lang, and sets <meta name="theme-color"> to the resolved --bg (#ffffff / #0e1213; two metas with media in system mode). Nothing else; under 1 KB; _headers gives /boot.js Cache-Control: no-cache.
lib/theme.ts: readThemePreference, writeThemePreference, useResolvedTheme() (system follows prefers-color-scheme live through a matchMedia listener, read with useSyncExternalStore), and useForcedLightTheme(), which applies light while its component is mounted and restores the preference on unmount.
AdminLayout, StudentLayout and FocusLayout call useForcedLightTheme(). The front door and system pages follow the preference. No user-facing toggle ships; the server copy of the preference (users.preferences) arrives in R4.
Brand.tsx gains theme="auto", swapping the colour and on-dark logo and mark by the resolved theme; onDark stays for always-dark surfaces.
Unit tests: default, invalid value, storage throwing, system following an emulated media change, forced light restoring the preference.
theme.spec.ts: with quizzivy.theme=dark, /login's document has html.dark and a dark computed background before React mounts (no light flash); with system and page.emulateMedia({ colorScheme: "dark" }) the page follows live; /admin renders light under a dark preference.

T-R1.4 — Motion and icons

Depends on: T-R1.1 Touches: web/src/index.css, web/src/components/shared/{MarqueeText,LiveDot}.tsx (new), web/src/lib/icons.ts (new), web/tests/units/shared/{marquee-text,live-dot}.test.tsx (new), web/tests/units/lib/icons.test.ts (new) Size: S Done when:

Keyframes from the deck: qz-marquee (to translateX(calc(-50% - 16px))), qz-pulse (opacity 1 → .35, 1.6 s), qz-spin, qz-shimmer (1.4 s linear), qz-breath (1.8 s), qz-indet (1.2 s). Under prefers-reduced-motion each has a static state, not a shortened one: marquee → ellipsis, pulse → solid dot, shimmer → flat --muted, breath → still mark, indeterminate → a fixed 40% bar. The existing global reduced-motion block stays.
MarqueeText animates only when its text overflows (measured with a ResizeObserver, not the deck's 600 ms polling), duplicates the text with the copy aria-hidden, exposes the full text once to assistive tech and in title, pauses on hover and on focus-within (WCAG 2.2.2, DG-33), and renders an ellipsis under reduced motion.
LiveDot is a 7px --success dot using qz-pulse, aria-hidden (the text beside it carries the meaning), static under reduced motion.
lib/icons.ts maps the deck's kebab names to canonical lucide-react components for icons chosen by data: the role icons the Admin page offers (shield, graduation-cap, hand-helping, user, key-round, crown, briefcase, book-open, users, clipboard-check, headset, star) and the toast tones. Statically chosen icons keep direct imports.
icons.test.ts: every mapped component is icons[<PascalName>] from lucide-react's canonical icons export, so no deprecated alias can enter the map; pnpm lint (sonarjs deprecation) clean.
Unit tests: overflow detection with a stubbed ResizeObserver, pause on focus, ellipsis under reduced motion, accessible name spoken once; LiveDot static under reduced motion.

T-R1.5 — Primitives: controls, additive

Depends on: T-R1.1, T-R1.2, T-R1.4 As built (#163, #165): button, input, textarea, label, field, badge, avatar, card, skeleton, kbd and separator carry the deck geometry. Select, the date/time picker, switch, checkbox, segmented, tabs, table, toggle and toggle group had no consumer in R1 and moved to the release of their first consumer (T-R3.5, T-R4.1, T-R4.2), together with the deck-scale context their portaled popovers need. Touches: web/src/components/ui/{button,input,textarea,label,field,select,calendar,switch,checkbox,segmented,tabs,badge,avatar,card,skeleton,table,toggle,toggle-group,kbd,separator}.tsx, web/src/components/shared/{DateTimeField,PasswordInput,StatusBadge}.tsx, web/tests/units/ui/{icon-scale,avatar,select-and-date}.test.tsx, web/tests/units/ui/deck-scale.test.tsx (new) Size: L Done when:

T-R1.6 — Primitives: overlays, feedback and focus

Depends on: T-R1.5 Touches: web/src/components/ui/{dialog,dropdown-menu,popover,sonner,alert}.tsx, web/src/components/ui/sheet.tsx (new), web/src/lib/toast.ts (new), web/src/index.css, web/tests/units/ui/{toast-tones,sheet,focus-visible}.test.tsx (new) Size: M Done when:

One global :focus-visible style: 2px solid --focus, offset 2px, on every interactive element in both themes and both scales (DG-30). Inputs add it to the border change. The vendored focus-visible:ring-[3px] ring-ring/50 classes are replaced. Pointer focus shows nothing. focus-visible.test.tsx covers button, input, select trigger, checkbox, switch, tab, menu item and dialog close.
Dialog: --overlay backdrop; variant="console" at top 8vh, 480 wide by default (420/500/520/560/720 options), r12, max-height 86vh; variant="student" 440 wide at 18% (12% on phones), r14. Focus is trapped, Esc closes, focus returns to the trigger. (The student variant was not built in R1; T-R3.7's Join dialog carries the frame as a class recipe, centred from 768 and 12% from the top below it, see 73-r3.md.)
Sheet (new, on Radix Dialog from the installed radix-ui): right drawer 380/420/440 (min(…, 100%)) and bottom sheet (r16 top), same focus rules; --z-sheet.
Dropdown menu 220 default, r10, p5, shadow-float; items r6 13px with icon or check, meta, danger-ink item, separator, disabled at .45, optional title, max-height 60vh; roving focus. Popover r10, shadow-float, p4.
Toast tones (DG-32): success, error, warning, info, each with its own icon (circle-check, circle-alert, triangle-alert, info) in its -ink colour; card r10; one at a time; success and info last 2.4 s as in the deck, error and warning 6 s with a close button; errors announced assertively, the rest politely. lib/toast.ts exposes the four tones; the plain toast() calls old screens make keep working in a neutral tone.
Alert tones muted, info, warning, danger: soft background, ink text, 16px icon, r10, padding 10/12.
Tests: each toast tone's icon and live-region politeness; sheet focus trap and Esc; dialog variant classes.

T-R1.7 — The brand frame for the front door and system pages

Depends on: T-R1.3, T-R1.5 Touches: web/src/components/shared/BrandFrame.tsx (new), web/src/features/auth/AuthLayout.tsx, web/src/app/pages/SystemFrame.tsx (new), web/src/app/pages/ErrorScreen.tsx (removed), web/src/lib/config.ts (new), .env.example, .github/workflows/deploy.yml, web/tests/units/auth/auth-layout.test.tsx (new) Size: S Done when:

BrandFrame: root with data-scale="deck" on --bg; brand panel flex: 0 0 44%, max 620, --sidebar background, right border, padding 40/48, column with space-between (32px theme-aware horizontal logo, a middle slot, a bottom caption); main column centred, padding 48 wide and 32/20 narrow; narrow shows a 28px logo above the content with 28px below; content max 380, gap 20.
AuthLayout: the panel appears from 900px (auth breakpoint) on login, forgot-password and change-password only; join (and Joined) is always one column. Panel text: headline 30/600/-0.02em/lh 1.2 balanced ("Tests, lessons and practice for your English classes."), the org name at 15 muted, and at the bottom 12.5 muted "Need help signing in? Ask your teacher or the front desk." — vi written first.
SystemFrame: the same frame with the art panel from 1024 (lg): a 300px SVG in currentColor, the org name as caption; content h1 24/600, body 14.5/1.6, a detail slot, full-width stacked actions (38 wide / 44 narrow, r9), an optional divider slot, footnote 13 muted centred.
lib/config.ts exports orgName (VITE_ORG_NAME), frontDesk (VITE_ORG_FRONT_DESK_PHONE, VITE_ORG_FRONT_DESK_HOURS, shown verbatim in both locales as the centre's own wording) and appVersion (web/package.json version). An unset value hides its line. .env.example documents them as public; deploy.yml passes them from repository vars. These three are the only VITE_ORG_* values R1 defines; R11 extends this file with VITE_ORG_EMAIL and VITE_ORG_ADDRESS, and none of them is removed later (R5 falls back to them).
Prototype chrome never ships: no switcher pills, canvas theme button, demo-accounts box or "Try …" hint; a test asserts none of their strings render.
Unit tests: panel present at 900 and absent at 899 on /login, never on join; org lines hidden when unset.

T-R1.8 — Sign in, Forgot password and the Google callback

As built (#169, #172): the client maps INVALID_CREDENTIALS and PASSWORD_UNCHANGED to its own keys (login.invalidCredentials, changePassword.errors.unchanged) while the server also localises both; every other code shows the server's message. The web app owns these two, in the deck's wording, and the contract's ErrorCode description states the exception (#183, decided 2026-10-04). Depends on: T-R1.6, T-R1.7 Touches: web/src/features/auth/pages/{LoginPage,GoogleCallbackPage}.tsx, web/src/features/auth/pages/ForgotPasswordPage.tsx (new), web/src/features/auth/loginSchema.ts, web/src/app/router.tsx, web/src/lib/i18n/locales/{vi,en}.json, server/internal/modules/identity/http/auth.go, web/tests/units/auth/{login,login-without-google,callback-preload}.test.tsx, web/tests/units/auth/forgot-password.test.tsx (new), web/tests/e2e/smoke.spec.ts Size: M Done when:

/login per #login: h1 "Sign in"; subtitle "Welcome back.", or "Sign in to join {className}." when a join context is present (T-R1.9); Google button 46/r10 full width with the 18px GoogleMark and a busy state (aria-busy, spinner) — still our PKCE flow, never the GIS SDK; the "or with email" divider; one role="alert" (danger-soft, danger-ink, circle-alert) for "Enter your email and password." (client) or the server's message, cleared on the next edit; email 46 (autocomplete="username", placeholder "[email protected]"); password with "Forgot password?" in the label row and a 36px show/hide button whose aria-label switches; submit xl "Sign in" / "Signing in…" with aria-busy, never a dead disabled button; footer "Have a class code? Join a class".
Enter submits; ?next= and the must-change redirect are unchanged (destinationAfterSignIn); in a join context a successful sign-in continues the join.
The server's INVALID_CREDENTIALS message becomes the deck's sentence, vi first ("Email và mật khẩu không khớp. Hãy kiểm tra lỗi gõ, hoặc nhờ giáo viên đặt lại mật khẩu."), English when Accept-Language prefers it, using the language.Matcher approach of imports/http/errors.go. It stays one message for an unknown email, a wrong password and a disabled account. A 429 shows the server's RATE_LIMITED message (DG-40).
/forgot-password (new, lazy, panel from 900): 44px key-round tile r12; h1 "Forgot your password?"; the body; an info card with the Google row ("Signed up with Google? You do not need a password. Use Continue with Google.") and the front-desk row (phone icon, "Front desk · {phone} · {hours}", hidden when unset, DG-41); outline xl "Back to sign in". It makes no request.
The Google callback has a loading state ("Signing you in…") and an error state on the auth layout with a way back to /login that keeps the join context (DG-40); the student-home preload stays (callback-preload.test.tsx green).
New and changed keys under login.*, forgot.*, callback.*: vi written first, en verbatim from the deck, listed in the PR.
Unit tests rewritten with the screen: fields and autocomplete, toggle labels, the alert clearing, the join subtitle, the busy state, the forgot page with and without front-desk config, the callback states. smoke.spec.ts "lands on /login" and live E2E 2 (answers-persist.live.spec.ts, password sign-in) green.
Compared with #login and #forgot at 360, 768, 1024, 1280, 1440, light and dark.

T-R1.9 — Join and Joined

Depends on: T-R1.7, T-R1.8 Touches: web/src/features/join/{code,api}.ts, web/src/features/join/context.ts (new), web/src/features/join/pages/JoinPage.tsx, web/src/features/join/components/{JoinCodeField,ClassPreviewCard,JoinedState}.tsx (new), web/src/features/join/pages/JoinConfirmPage.tsx (removed), web/src/features/join/components/JoinCodeForm.tsx (removed), web/src/layouts/PublicLayout.tsx (removed), web/src/app/router.tsx, web/src/features/auth/pages/{LoginPage,GoogleCallbackPage}.tsx, web/tests/units/join/code.test.ts, web/tests/units/join/{join-page,joined}.test.tsx (new, replacing confirm.test.tsx), web/tests/e2e/join.spec.ts Size: M Done when:

T-R1.10 — Change password with server-enforced rules

As built (#172): the meter scores 0–4, not 0–3: one for any password (the browser cannot see the temporary password, so it cannot fail that rule), one for each client-checkable rule, and one at twelve characters or more (web/src/lib/password.ts, passwordStrength). Depends on: T-R1.7 Touches: api/openapi.yaml, server/gen/openapi/, web/src/lib/api/schema.d.ts, server/internal/modules/identity/{domain/errors.go,application/command/change_password.go,http/account.go}, server/internal/platform/httpx/errors.go, web/src/features/auth/changePasswordSchema.ts, web/src/features/auth/pages/ChangePasswordPage.tsx, web/src/components/shared/PasswordRules.tsx (new), web/src/features/auth/components/SettingsSections.tsx, server/internal/modules/identity/application/tests/change_password_test.go, server/internal/core/router/tests/validate_test.go, web/tests/units/auth/change-password.test.tsx Size: M Done when:

Contract: changePassword's newPassword keeps minLength: 8, maxLength: 512 and gains pattern: '[\p{N}\p{P}\p{S}]'; the description states the rules. A violation is 400 VALIDATION_FAILED from httpx.ValidateRequests, with a message that states the rule (vi, or en when the request prefers it; #189); no hand-written check is added. make gen output committed as its own commit.
New ErrorCode PASSWORD_UNCHANGED (400, message vi then en): while mustChangePassword is set, the new password is verified against the current (temporary) hash and refused if it matches; otherwise it is refused when equal to the verified currentPassword.
Existing passwords are never re-validated and sign-in is unchanged. A test proves PasswordManager.Temporary()'s output satisfies the pattern (word-word-NN in R1, word-word-word-NN since F-53).
The zod schema carries the same two rules, shared by the page and the Settings password section (whose layout waits for R3/R4); the settings section shows the same messages.
The page per #change, panel from 900: h1 "Choose your password", the body, "New password" (46px, autocomplete="new-password"), the strength meter (4 bars, 4px, r4, gap 4; score = rules 1–2 met plus one at 12 characters or more; filled bars --danger at ≤ 1, --warning at 2, --success at ≥ 3, the rest --muted), the checklist ("At least 8 characters", "A number or symbol", "Different from the temporary password" — the third stays a neutral stated rule, since the browser cannot see the temporary password, and turns into the server's message if refused), "Type it again" with "The two passwords are different." (danger border, 12.5 danger-ink).
"Save and continue" (48px) is aria-disabled until rules 1–2 pass and the fields match; a click before then reveals the errors. After success: destinationAfterSignIn, or the pending join (T-R1.9).
Server tests: "matkhau1" and "mật khẩu!" accepted, "mậtkhẩuđẹp" (letters only) refused, PASSWORD_UNCHANGED on both paths. Web tests: meter scores, checklist, mismatch, aria-disabled reveal, the server error shown.
Compared with #change at the five widths, light and dark.

T-R1.11 — The API client: unavailable is not signed out

Depends on: — Touches: web/src/lib/api/{client,errors}.ts, web/src/features/auth/useSession.ts, web/src/stores/appState.ts (new), web/tests/units/api/client.unavailable.test.ts (new), web/tests/units/auth/bootstrap.test.tsx Size: S Done when:

performRefresh distinguishes three outcomes: refreshed; refused (401 or 403 from /auth/refresh, today's session-lost path); unavailable (network TypeError, 503, other 5xx), which rejects every waiting request with a retryable error and never calls onSessionLost. The refresh stays single-flight; client.refresh.test.ts is untouched and green.
A 503 whose envelope code is MAINTENANCE calls a new setMaintenanceHandler with { startsAt, endsAt } before the error is thrown, from both api() and uploadFile().
Every request sends Accept-Language set to the app locale (vi or en), so server messages match the UI rather than the browser.
stores/appState.ts (zustand) holds the boot phase and the overlay (none, maintenance, expired, update) with the window for maintenance.
useBootstrapSession: 401 → signed out (as today); network failure → boot phase offline, the session untouched; MAINTENANCE → overlay maintenance; any other error → the unexpected-error page with its requestId. An offline cold load no longer lands on /login.
Tests: a network failure or a 503 MAINTENANCE during refresh does not call onSessionLost; a refused refresh does; five concurrent 401s with an unavailable refresh make one refresh call and all reject retryably; Accept-Language is sent; the bootstrap outcomes.

T-R1.12 — Maintenance windows: schema and the operator command

Depends on: — Touches: migrations/NNNNN_create_maintenance_windows.sql (new), server/internal/core/maintenance/windows.go (new), server/internal/core/maintenance/maintenance.go (package comment), server/internal/core/maintenance/cli.go (new), server/cmd/maintenance/main.go, server/internal/core/maintenance/tests/{windows_test.go,cli_test.go} (new), server/internal/platform/db/tests/privileges_test.go, docs/setup/operations.md, docs/plan/20-data-model.md (the advisory-lock registry) Size: M Done when:

T-R1.13 — Maintenance windows in the API: status, the 503 gate, the start guard

As built (#178): the attempts port is StartGuard and its adapter adapters.AttemptStartGuard. The gate's position is pinned in maintenance_gate_test.go (a preflight is answered by CORS; the limiter never counts a gated request), since the middleware order is pinned by validate_test.go and hardening_test.go, not router_test.go. Depends on: T-R1.12 Touches: api/openapi.yaml, server/gen/openapi/, web/src/lib/api/schema.d.ts, server/internal/modules/availability/{domain,application/query,repositories,http}/ (new), server/internal/core/wiring/{availability.go (new),attempts.go}, server/internal/core/adapters/availability.go (new), server/internal/core/router/{router.go,ratelimits.go,modules.go,server.go}, server/internal/platform/httpx/maintenance.go (new), server/internal/modules/attempts/{repositories/store.go,domain/errors.go}, server/internal/core/router/tests/maintenance_gate_test.go (new), server/internal/core/router/tests/{auth_middleware_test.go,public_routes_test.go,router_test.go}, server/internal/modules/availability/repositories/tests/guard_test.go (new), server/internal/core/maintenance/tests/windows_test.go, server/internal/modules/attempts/application/tests/create_test.go Size: M — high-risk area (attempts) Done when:

T-R1.14 — A running attempt adopts a moved deadline

Depends on: — Touches: api/openapi.yaml, server/gen/openapi/, web/src/lib/api/schema.d.ts, server/internal/modules/attempts/{repositories/autosave.go,repositories/submit.go,application/command/save.go,http/attempts_handlers.go,domain/errors.go}, web/src/features/take-test/{store.ts,groupPlayback.ts,draft.ts}, server/internal/modules/attempts/application/tests/{autosave_test.go,submit_test.go}, web/tests/units/take-test/{deadline,group-playback}.test.ts Size: M — high-risk area (features/take-test/, attempts) Done when:

saveAnswers 200 gains required deadlineAt (the row's current deadline_at, already read by autosave.go). Additive: an open v0.6 tab ignores it.
submitAttempt with reason timer_expired while the server deadline is more than 5 s away answers 409 DEADLINE_NOT_REACHED with details { deadlineAt } (new ErrorCode). manual and auto_submit are unchanged; a timer_expired within 5 s of the deadline, or after it, behaves as today.
The store adopts the server's deadline from either response: deadlineAt updates, the existing subscription re-arms the single deadline timer, a refused submit returns submitState to idle, the group playback lock and the local draft carry the new deadline. A teacher's Extend now reaches an open attempt on its next autosave instead of on reload.
Before and after the PR: the canaries (publish_snapshot_test.go, audio-player.test.tsx, the integrity events canary, client.refresh.test.ts, router-chunks.test.ts) and pnpm test:unit tests/units/take-test tests/units/integrity; live E2E 5–8 (timer-expiry, integrity-away, session-takeover, audio-plays) and E2E 9 (payload-leak.live.spec.ts) green, the key walk still finding no isCorrect, sampleAnswer, acceptedAnswers or transcript.
Server tests: autosave returns the extended deadline after an Extend; an early timer_expired is refused with the deadline; the 5 s boundary is accepted. Web tests (fake timers): a later deadline from autosave re-arms the timer; DEADLINE_NOT_REACHED returns to idle and re-arms at the new time; no double submit.

T-R1.15 — System pages

Depends on: T-R1.7 Touches: web/src/app/pages/{ForbiddenPage,errorArt}.tsx, web/src/app/pages/{NotFoundPage,MaintenancePage}.tsx (new), web/src/app/ErrorBoundary.tsx, web/src/app/router.tsx, web/src/components/shared/CopyButton.tsx (new), web/src/lib/i18n/locales/{vi,en}.json, web/tests/units/errors/screens.test.tsx, web/tests/integration/router-chunks.test.ts Size: M Done when:

Four pages on SystemFrame, the deck's four SVGs copied verbatim into errorArt.tsx (currentColor, aria-hidden), correct in both themes:
- 404: h1, body, the path chip with the real location.pathname, "Go to home", "Go back" (history.back() when there is history, else home), footnote.
- 403: h1, body, the identity card (30px avatar with DG-22 initials, full name, "Signed in"), "Go to my home", "Sign in with another account" (signs out, then /login). Signed out: no card and a primary "Sign in".
- Unexpected error: h1, the body with its promise ("…your saved answers are safe", pinned literally in the test), "Reload the page", "Go to home", a divider, the Error ID row (requestId first, else four random bytes as xxxx-xxxx, user-select: all) with CopyButton: "Copy" → "Copied" for 2 s announced politely; a clipboard failure says "Couldn't copy. Select the ID and copy it." instead.
- Maintenance: h1 "Quizzivy is being updated", "We'll be back by {time}. Tests that close during the update are extended." (times in APP_TIME_ZONE, the date added when not today), the status list (clock in warning-ink, "Started {time}", "about {n} min"; circle-check in success-ink, "Answers and results saved"), primary "Check again", footnote. Fed by the 503 details or GET /public/status (T-R1.16 wires it).
NotFoundPage.tsx replaces ErrorBoundary.tsx's NotFound export: router.tsx's * route and ErrorBoundary's router-404 branch both render it, and the old export is deleted in the same PR, so there is one 404. errorArt.tsx's existing NotFoundArt becomes the deck's 404 SVG rather than gaining a second 404 illustration.
"Home" is the caller's console, homePathFor(user), and /login when signed out (DG-43).
The four pages and SystemFrame are in the entry chunk (they must render when a lazy chunk cannot load); router-chunks.test.ts gains that assertion and removes none.
Keys notFound.*, forbidden.*, error.*, maintenance.* rewritten vi first, en from the deck, listed in the PR.
screens.test.tsx rewritten: home per role and signed out, the signed-out 403, copy success and failure, requestId preference, maintenance times.
Compared with #404, #403, #error, #maintenance at the five widths, light and dark.

T-R1.16 — Splash and app states

As built (#180): AppFrame renders beside RouterProvider, not as the root route's element: React Router 7.18 renders the root's HydrateFallback, not its element, while a deep link's lazy routes load, and a failed lazy import replaces the root with the ErrorBoundary. The root route has HydrateFallback: () => null. A refused session keeps a signed-in user (auth.expired, token dropped) so the page stays mounted under the sign-in-again overlay, and a 401 while expired skips the refresh. The build id is QUIZZIVY_BUILD, which deploy.yml sets to the resolved commit, not git rev-parse; any other build gets an id of its own. The overlays render light over the old consoles, which force light until R3 and R4 rebuild them. Depends on: T-R1.4, T-R1.11, T-R1.13, T-R1.15 Touches: web/index.html, web/src/app/AppFrame.tsx (new), web/src/app/boot/{BootSplash,AppStateLayer}.tsx (new), web/src/app/boot/{handoff,version,status}.ts (new), web/src/app/{router,providers}.tsx, web/src/app/guards/{RequireSession,HomeRedirect}.tsx, web/src/features/integrity/useIntegrityMonitor.ts, web/vite.config.ts, web/public/_headers, web/tests/units/boot/{splash,app-state,version}.test.tsx (new), web/tests/units/integrity/overlay-pause.test.ts (new), web/tests/e2e/splash.spec.ts (new), web/tests/integration/router-chunks.test.ts Size: L Done when:

T-R1.17 — Old consoles under the new palette and font

As built (#181): a throwaway Playwright harness measured every /app route, the engine included, and every /admin route except the import detail, import review and question-group editor pages, at 1280 and 360, on the seeded data plus five bank questions created for the run (the seed has no bank questions, imports or question groups), and diffed the result with the same run against develop: contrast of every text node, overflow, clipping, truncation, wrapping, and a focused-versus-blurred style check at each of the first 40 Tab stops. Two fixes: the old consoles' success badge takes --success-ink (4.28:1 before), and the grading bar's details line yields before the student's name. The teacher console's 768px layout at 360 is as on develop; R4 builds its phone layout. Depends on: T-R1.1 … T-R1.6 Touches: token-level fixes in web/src/** only; no layout change Size: M Done when:

Every /admin route and every /app route, including the engine on the three-part paper from seed/05-dev-sections.sql, is checked at 1280 and 360 in (forced) light, with data shaped like production's.
Contrast and overflow regressions from the palette and font are fixed by token mapping or by replacing a legacy class, never by layout. Be Vietnam Pro is wider than Inter: the longest Vietnamese strings in sidebars, table headers and buttons are checked, and a new wrap or truncation is fixed with the existing min-width and ellipsis patterns.
Keyboard focus is visible on every control of the old consoles (NFR-F02).
Existing unit and E2E tests green unchanged, except assertions of colour class names (listed in the PR). Anything not fixed becomes an issue.

T-R1.18 — Docs for R1

Depends on: T-R1.1 … T-R1.16, T-R0.3, T-R0.4 Touches: docs/quizzivy-spec-v0.3.md, AGENTS.md, docs/plan/70-redesign-overview.md, docs/plan/20-data-model.md, docs/plan/50-nfr-registry.md, docs/design/gaps.md Size: S Done when:

Spec, version bumped per §18: the "Availability: R1" markers T-R0.3 placed are removed from what shipped; §4 org details from build-time config (R5's settings later take precedence, these values staying as the fallback); §5.4 the password rules and PASSWORD_UNCHANGED; §6.1 the alphabet prose corrected (the string contains L); §6.2 the inline preview, Joined and the password path; §9 /forgot-password, the system pages, the splash states and the overlays; §10 integrity paused under the maintenance and expired overlays, and an extension reaching an open attempt on its next autosave; §12 the tokens as built (the three accessibility tokens, data-scale="deck"); §13 maintenance_windows; §15 GET /public/status, the 503 envelope, MAINTENANCE_SCHEDULED, DEADLINE_NOT_REACHED, PASSWORD_UNCHANGED, saveAnswers.deadlineAt.
AGENTS.md: the "Redesign in progress" R1 bullet replaced by what now holds (deck geometry only under data-scale="deck" until R5; old consoles force light; boot.js); seven open operations with theOpenSeven; the middleware section notes the maintenance gate sits outside the router, between CORS and the mux; Design names --focus and no-raw-colours.test.ts.
70-redesign-overview.md §4.2 already carries the whole open-operation schedule (six at v0.6.0, R1's getPublicStatus making seven, then R5, R7 and R11). Checked, not rewritten: R1's entry matches what shipped (GET /public/status, theOpenSeven); any difference is corrected there.
20-data-model.md: a maintenance_windows section, its inventory row and a deviation (the app role reads only; the operator writes through cmd/maintenance; extensions are audited as System).
NFR registry: F02 (visible focus everywhere) ✅ with evidence; F04 rewritten to the deck's motion list with reduced-motion statics; E05's evidence names the entry-chunk assertions.
gaps.md: DG-02's alphabet wording fixed; DG-20's Vietnamese-default rule, DG-22, DG-30 … DG-35, DG-40, DG-42 and DG-43 "Meanwhile" rules marked as built in R1, naming the tokens and components. DG-20's glossary review is sent to the design team with the list of R1's new and changed keys.

T-R1.19 — Verification

Depends on: T-R1.1 … T-R1.18 Touches: — Size: S Done when:

70 §8 step 1 run locally in order, judged by exit code, on work/redesign-r1 with develop merged in: make lint, make gen-check, make test-api (docker compose up -d db minio), goose up/down/up, pnpm lint, pnpm typecheck, pnpm format:check, pnpm test:unit, pnpm test:integration, pnpm build, pnpm e2e, pnpm e2e:content, pnpm e2e:live (auth, join and take-test changed), node scripts/check-design-deck.mjs.
The app beside the deck (design-deck on 5175, the app on 5173 with the API), dev server confirmed fresh: every Sign in, System and Splash state at 360, 768, 1024, 1280 and 1440, light and dark, measured with getBoundingClientRect; the table (screen × width × theme → match / fixed / DG id) is in the release PR.
A local maintenance rehearsal: a student mid-attempt, window-schedule -apply two minutes ahead; a second student's start is refused; the window opens and both tabs show the overlay; after window-end the overlay closes, the first student's timer shows the extended deadline, and the attempt submits normally.
Vite, the API and the deck server stopped; only the compose services used were started.

Release checklist

Every Done-when box above is ticked on work/redesign-r1; the R0 PRs (T-R0.1 … T-R0.9) are on develop; develop is merged in and T-R1.19 is green.
Every PR's new vi keys reviewed by Thuong (D11); the answers applied.
Security: the leak review for GET /public/status is in its PR; its rate-limit test passes; theOpenSeven is the only change to the open list; E2E 9 green after the saveAnswers change.
Migration rehearsed on a Neon branch of production: goose up, then maintenance window-schedule as a dry run against the branch (it reports counts and writes nothing); branch deleted.
Production prerequisites: repository variables VITE_ORG_NAME, VITE_ORG_FRONT_DESK_PHONE and VITE_ORG_FRONT_DESK_HOURS set (optional; unset lines are hidden); web/package.json version set to 0.7.0 (the splash label). No new secret.
Deploy outside exam windows: no assignment open with an attempt in progress (the release changes saveAnswers and submitAttempt).
work/redesign-r1 → develop (--no-ff); release/0.7.0 cut from develop with the release notes, the spec version confirmed and the NFR registry reviewed.
Release notes say: the new look (palette, Be Vietnam Pro, visible keyboard focus) with the consoles' layout unchanged; the new sign in, the forgot-password information page, the join page that shows the class before sign-in and confirms the join; new passwords need at least 8 characters with a number or symbol and must differ from the temporary one, while existing passwords keep working; the new error pages; the loading screen, which now retries when offline instead of signing out and offers a reload after an update; maintenance windows (the runbook in docs/setup/operations.md), with tests closing during maintenance extended; an open test now picks up a teacher's extension without a reload; a Cloudflare Pages rollback loses no data, but not every API change is additive, so the old web meets new refusals (the password rule among them, #189).
release/0.7.0 → main with Thuong's go (--no-ff); Deploy runs the API (release_command migrates) then Pages.
Smoke on production: /livez; /healthz with database: ok; the worker group running; GET /public/status answers {"maintenance":null}; /login in the new design; a join deep link with a known code shows the inline card; an unknown path shows the new 404; the owner signs in and lands on /admin in the old console with the new palette and font; a student signs in; maintenance window-list runs against production.
Tag v0.7.0; back-merge main → develop by PR; close the R1 epic issue. Rollback is roll forward (70 §8).

Open items

O-R1.1 — Does a maintenance window pause the import worker? Default: no. The window gates HTTP only and the worker keeps processing imports it already holds; the runbook says so. If a window is ever needed for work that must not race imports, the worker gains the same snapshot check. Needed before the first window scheduled for database work.
DG-30, DG-31 — the interim accessibility tokens (--focus, --input, --danger-solid) ship with the values above until the design team answers; the token test fails on any answer below the thresholds.
DG-40 — auth states the deck does not draw (Google callback loading and error, 429 copy, a non-student opening a join link, enrolment failing after sign-in) are built from deck primitives and listed for the design team's sign-off.
DG-41 — front-desk phone and hours come from build-time config. From R5 the Organization settings take precedence and the build values remain the fallback.
DG-42 — no Admin control for maintenance windows; the command line is the only way to schedule one until the deck draws a control.

_{Generated from docs/plan/71-r1.md. Edit that file in the repository; changes made on this page are overwritten.}

Plan 71 R1 - SekiroKenjii/Quizzivy GitHub Wiki

R1 — Foundations and front door (v0.7.0)

T-R1.1 — Tokens and the token test

T-R1.2 — Be Vietnam Pro, self-hosted

T-R1.3 — Theme preference and the boot script

T-R1.4 — Motion and icons

T-R1.5 — Primitives: controls, additive

T-R1.6 — Primitives: overlays, feedback and focus

T-R1.7 — The brand frame for the front door and system pages

T-R1.8 — Sign in, Forgot password and the Google callback

T-R1.9 — Join and Joined

T-R1.10 — Change password with server-enforced rules

T-R1.11 — The API client: unavailable is not signed out

T-R1.12 — Maintenance windows: schema and the operator command

T-R1.13 — Maintenance windows in the API: status, the 503 gate, the start guard

T-R1.14 — A running attempt adopts a moved deadline

T-R1.15 — System pages

T-R1.16 — Splash and app states

T-R1.17 — Old consoles under the new palette and font

T-R1.18 — Docs for R1

T-R1.19 — Verification

Release checklist

Open items

⚠️ GitHub.com Fallback ⚠️

Plan 71 R1 - SekiroKenjii/Quizzivy GitHub Wiki

R1 — Foundations and front door (v0.7.0)

T-R1.1 — Tokens and the token test

T-R1.2 — Be Vietnam Pro, self-hosted

T-R1.3 — Theme preference and the boot script

T-R1.4 — Motion and icons

T-R1.5 — Primitives: controls, additive

T-R1.6 — Primitives: overlays, feedback and focus

T-R1.7 — The brand frame for the front door and system pages

T-R1.8 — Sign in, Forgot password and the Google callback

T-R1.9 — Join and Joined

T-R1.10 — Change password with server-enforced rules

T-R1.11 — The API client: unavailable is not signed out

T-R1.12 — Maintenance windows: schema and the operator command

T-R1.13 — Maintenance windows in the API: status, the 503 gate, the start guard

T-R1.14 — A running attempt adopts a moved deadline

T-R1.15 — System pages

T-R1.16 — Splash and app states

T-R1.17 — Old consoles under the new palette and font

T-R1.18 — Docs for R1

T-R1.19 — Verification

Release checklist

Open items

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️