Make dark mode a user setting with a System option

[alexeygrigorev]

User outcome

A member chooses once, in their account settings, whether the site follows their operating
system's appearance (System) or always uses Light or Dark. A visitor with no account gets the
same System-by-default behaviour locally. Nobody who already chose a theme sees it change when
this ships.

This is a bounded P2 slice: one preference, one control, no preferences framework.

Normative links and current contract (verified at main, 9603342)

• _docs/design/design-5a.md — the token table is mirrored on body.dark-mode; light/dark
  pairs are the only sanctioned colour source for design 5a pages.
• Storage today: anonymous choice in localStorage['darkMode'] ('true'/'false'), read by
  the pre-paint bootstrap in templates/core/_site_shell_head.html:32-47 (anonymous only,
  key read at line 39) and by the toggle script in
  templates/core/_site_shell_foot.html. The Playwright suites seed this key directly
  (e.g. playwright_tests/test_legal_footer_125.py:95,127).
• Server state today: CustomUser.dark_mode boolean (accounts/models.py:67, default
  False), published as DARK_MODE by course_management/context_processors.py:5-12 and
  rendered into the body element (class="dark dark-mode", data-dark-mode,
  data-authenticated, data-toggle-url) by every design 5a page template (e.g.
  templates/public/text_page.html:153-165).
• Endpoints today (both JSON POST; there is no cookie for dark mode — the foot include's
  "cookie endpoint" wording is loose, and no cookie is introduced by this issue):
  • POST /accounts/toggle-dark-mode/ (accounts/views/account_toggles.py:13-29): flips the
    boolean, returns {"dark_mode": bool}; consumed by the design 5a masthead script and by
    the legacy courses/static/dark_mode.js.
  • POST /accounts/settings/toggle/ (update_account_toggle,
    accounts/views/account_toggles.py:32-64): sets an explicit value for an allowlisted
    field (only dark_mode today); consumed by the settings page's immediate-toggle row
    (course_platform_templates/accounts/account_settings.html:394-401 via
    courses/static/settings_toggles.js).
• Settings UI today: the account settings page (design 5a already) exposes a "Use dark mode"
  checkbox (accounts/forms.py:94,105,124).
• prefers-color-scheme appears nowhere in repository CSS/JS/templates (verified); the
  effective default is light for everyone who never touched the toggle.
• Two theme implementations are live during the design 5a porting window: the token table
  under body.dark-mode (templates/core/_design_system.html) and the legacy
  courses/static/courses.css overrides (137 body.dark selectors) with
  courses/static/dark_mode.js. Both read the same storage key, body classes, data
  attributes, and flip endpoint.

Product decision (settled in grooming)

• Preference model: one three-state preference, System / Light / Dark, default
  System for new accounts and anonymous visitors.
• Migration semantics: existing dark_mode=True rows become Dark; existing
  dark_mode=False rows become Light. A stored False can be either "never chose" or "may
  have deliberately switched off", and mapping it to Light is the only choice that preserves
  every current user's rendered outcome at deploy time; nobody's theme flips because this
  shipped.
• Masthead pill: stays a two-state quick override that writes an explicit Light or
  Dark (from System, the pill writes the opposite of the currently effective theme).
  Returning to System happens in account settings only — no three-state cycling on a
  single button.
• Server vs browser: the server cannot see the OS preference, so System is resolved in
  the browser by the pre-paint bootstrap, which extends from anonymous-only to any visitor
  whose resolved preference is System.

Scope

1. Model/migration: replace CustomUser.dark_mode with
   theme_preference = CharField(choices=[system, light, dark], default="system"); data
   migration maps True → dark, False → light; migration-drift check green. One source of
   truth — no dual columns.
2. Context: course_management/context_processors.py publishes THEME_PREFERENCE (raw)
   and keeps publishing DARK_MODE as the server-effective boolean (system resolves to
   light server-side), so legacy templates and pages keep rendering exactly as today.
3. Templates: body element gains data-theme-preference="{{ THEME_PREFERENCE }}";
   server-rendered dark dark-mode classes remain for light/dark. The head bootstrap
   (_site_shell_head.html) resolves System via
   matchMedia('(prefers-color-scheme: dark)') pre-paint for anonymous and authenticated
   alike, and keeps honouring the stored explicit choice first.
4. Anonymous storage: new key themePreference (system|light|dark); the legacy
   darkMode key is read as an explicit Light/Dark choice when the new key is absent and
   is never written again. Existing visitors and the Playwright suites that seed darkMode
   keep working unchanged.
5. Endpoints:
   • update_account_toggle allowlist gains theme_preference, accepting exactly
     system|light|dark (400 otherwise); response includes theme_preference and the
     effective dark_mode boolean.
   • toggle_dark_mode remains for legacy un-ported pages: it flips theme_preference
     between light and dark and keeps returning {"dark_mode": <effective bool>} so
     courses/static/dark_mode.js needs no change.
   • The design 5a masthead script switches to the value-setting endpoint and stops
     mirroring the preference into localStorage for authenticated users.
6. Settings control: replace the "Use dark mode" checkbox with a labelled three-option
   radio group (fieldset/legend "Theme"; options System — "Follows your device's appearance",
   Light, Dark), keeping the immediate-save row behavior and the accessible help/error
   relationships the page already uses.
7. Accessibility: aria-pressed on the masthead pill continues to reflect the effective
   dark state; declare color-scheme: light / color-scheme: dark alongside the existing
   body.dark-mode token table so native controls and scrollbars follow the theme.
8. Observability: account.toggle_updated records field="theme_preference" and the new
   value.
9. Focused Django tests (endpoints incl. validation and 405/302 boundaries, migration mapping,
   context processor, form) and Playwright core coverage for the new behaviour.

Non-goals

• No preferences framework, generic preference store, or per-device preference sync.
• No theming for the Django admin, emails, or rendered course artifacts.
• No live re-evaluation of prefers-color-scheme changes mid-session: System resolves at
  page load; reacting to an OS switch without a reload is future work.
• No changes to the legacy courses.css dark overrides, dark_mode.js, or legacy page
  templates beyond keeping their contracts working; porting those pages is the design 5a
  port's work, not this issue's. Legacy pages therefore keep server-effective rendering and
  do not follow the OS until they are ported.
• No cookie is introduced for dark mode (the timezone browser_timezone cookie pattern is
  not adopted here).
• No redesign of the masthead pill beyond its label/pressed-state semantics.

Dependencies

• None open. The design 5a shell, account settings page, and toggle endpoints all exist at
  main (Rebuild the public homepage on the design 5a mockup #179 work landed).

Acceptance criteria

• Migration maps existing rows dark_mode=True → theme_preference=dark and
  False → light; new users default to system; migration-drift check passes.
• Authenticated light/dark users get server-rendered body classes with no
  script-dependent flash; authenticated system users and anonymous visitors resolve
  System via prefers-color-scheme in the pre-paint bootstrap (no light flash when the
  OS is dark).
• Anonymous explicit choice persists in themePreference and wins over the OS; a legacy
  darkMode value still applies when themePreference is absent; nothing writes
  darkMode anymore.
• The masthead pill writes an explicit light/dark for both anonymous and
  authenticated visitors, updates aria-pressed and its label, and persists across
  reloads.
• Account settings shows the three-option Theme radio group; changing it saves
  immediately via update_account_toggle, applies without a full-page reload, and an
  invalid value is rejected with 400.
• POST /accounts/toggle-dark-mode/ still flips and returns {"dark_mode": bool};
  unauthenticated POST still redirects to login (302) and GET still returns 405.
• DARK_MODE remains server-effective for legacy templates; a legacy course page renders
  and toggles exactly as before.
• color-scheme is declared for both themes in the design system.
• Playwright core covers: OS-dark anonymous first visit renders dark; explicit choice
  overrides OS; authenticated system follows OS; reload shows no light flash; existing
  suites that seed darkMode stay green.
• Tester screenshots at desktop and mobile: light and dark variants of the homepage or a
  content page, and the settings page showing the three-state control, in both themes.

Browser scenarios

1. Fresh anonymous visitor, OS set to dark: first design 5a page renders dark with no light
   flash; the masthead pill shows the state; reload keeps dark.
2. Same visitor activates the pill: theme switches to the explicit opposite and survives
   reload even after switching the OS to light.
3. Member with preference Dark (migrated) opens any design 5a page: dark, server-rendered,
   no flash; the legacy course platform page they can still reach renders identically to
   today.
4. Member sets Theme to System in account settings with OS dark: next page load is dark;
   setting OS to light and reloading renders light.
5. Keyboard-only user tabs to the Theme group, changes options with arrows, and hears the
   saved state announced; the masthead pill's pressed state matches the visible theme.
6. All of the above at mobile width; nothing overflows or overlaps in the masthead.

[alexeygrigorev]

Grooming Complete

Researched the full current contract at main (9603342): storage key darkMode with the anonymous-only pre-paint bootstrap, server-side dark_mode boolean published as DARK_MODE, the two JSON POST endpoints (toggle-dark-mode/ flip and settings/toggle/ value-set), the design-5a body.dark-mode token table alongside the legacy courses.css/dark_mode.js implementation, and the account-settings checkbox. Confirmed prefers-color-scheme is used nowhere today.

Groomed as a bounded P2 slice with the open shape questions settled:

• One three-state preference (theme_preference: system/light/dark, default system) replaces the boolean in a single source of truth; migration maps True→dark, False→light so nobody's rendered theme changes at deploy.
• Anonymous default is System via prefers-color-scheme, resolved pre-paint; a new themePreference storage key supersedes the legacy darkMode key, which stays readable so existing visitors and the Playwright suites that seed it keep working.
• The masthead pill stays a two-state explicit override; System is chosen in account settings via a labelled three-option radio group.
• Both existing endpoints survive: the flip endpoint keeps its {"dark_mode": bool} contract for un-ported legacy pages; the value endpoint gains validated theme_preference. No cookie is introduced (there is none today; the foot include's "cookie endpoint" wording was loose).
• Explicit non-goals fence off a preferences framework, mid-session OS-change re-evaluation, legacy-page porting, and admin/email theming.

Labels: removed needs grooming; now enhancement, P2, auth, frontend, accessibility. No open dependencies — ready for engineering when scheduled.

[alexeygrigorev]

Software Engineer Report

Issue #183 is implemented in an isolated worktree and left uncommitted for tester review.

Base / head / worktree

• Base: a8f7499fc448f9a755fb24162856e6537b9aa663 (origin/main)
• Head: a8f7499fc448f9a755fb24162856e6537b9aa663 (same commit; all product changes are worktree-only)
• Branch / worktree: issue-183-engineer at /home/alexey/.grok/worktrees/git-dtc-website/issue-183-engineer
• Source mode: worktree (--include-worktree)
• No commit, no push, no PR. /home/alexey/git/dtc-website was not edited. Homepage copy/illustrations were not changed (body gained only data-theme-preference). No DESIGN_5A_* / design_5a identifiers were introduced.

Graph / plan digests

• Plan path: .tmp/verification/verification-plan.json
• Plan SHA-256: b9591c89975a552e2859c292c174a7de08e6971d6c8d841f53bf5d78eb6c9756
• Graph SHA-256: 4127118b4467a75b40b8dbadc4050b5b2dc3762b292aca93cd9309a4593bca19
• Source-tree manifest SHA-256: a2133ba05880a47dc1b76a141a6a05e58ca5a6f09ffc68be6900fc35c9d293d7
• Source tree OID: d0a86e6ce38ccf3b97378331cc583793689f51aa
• Render fingerprint SHA-256: ff54ca26e2eac4119d80a0b8fe3345d1ba7ea315f4ed7ea55ac88bd83a0ad5a5
• Environment SHA-256: 62fa21213247d65c01dfa68fc441baab2da54c2726913ff61d3a157c5e0326b5
• Plan created at: 2026-08-19T01:59:26Z
• Profile: full because of unknown_impact (conftest.py, test_support/tests/test_migrations.py) plus schema/migration, test-infrastructure, shared-runtime, auth/security/privacy, and render impact
• Browser profile: full
• Render impact: yes (templates, JS, context processor, browser harness)
• Required captures: / home, /__verification_missing__, /courses, /studio/ at desktop 1440×900 and mobile 390×844
• Risk flags: auth_security_privacy, dependency_toolchain, deployment_runtime, schema_migration, shared_runtime, test_infrastructure
• Direct nodes: app.courses, shared.accounts, shared.core, surface.configuration, surface.course_management, surface.course_platform_templates, surface.documentation, surface.playwright, surface.scripts, surface.templates
• Downstream nodes: django.accounts, django.api, django.content, django.core, django.courses, django.data, django.studio_courses
• Changed paths in plan: 84

Four disposition buckets

Bucket	Components	Reason
rerun	selector, evidence_validation, quality, django, playwright, container, screenshots	Fresh full regression / always-fresh control plane / render_inputs_changed
reused	(none)	No valid reuse envelope
skipped	(none)	—
not_applicable	compatibility, content_invariants	Outside impact / large-content closure

Reused provenance/expiry: N/A (nothing reused).

What shipped

One three-state theme_preference (system / light / dark, default system) replaces CustomUser.dark_mode. Migration 0013_theme_preference maps True → dark, False → light. Context publishes raw THEME_PREFERENCE and keeps server-effective DARK_MODE (system → light).

• Pre-paint bootstrap resolves System via prefers-color-scheme for anonymous and authenticated system users; stored themePreference wins; legacy darkMode is still read and never written by the design-system shell.
• Masthead pill stays a two-state explicit Light/Dark override and, for signed-in users, POSTs update_account_toggle (does not write localStorage).
• Account settings replaces the checkbox with a Theme fieldset (System — “Follows your device's appearance”, Light, Dark) that saves immediately.
• POST /accounts/toggle-dark-mode/ still flips light/dark and returns {"dark_mode": bool}; unauthenticated POST is 302; GET is 405.
• color-scheme: light / color-scheme: dark sit on :root and body.dark-mode.
• Observability records field="theme_preference" and the new value.

Changed files (product + tests + adoption ledgers)

New: accounts/migrations/0013_theme_preference.py, accounts/services/theme.py, accounts/tests/test_theme_preference_migration.py, playwright_tests/test_theme_preference.py

Core: accounts/models.py, accounts/forms.py, accounts/views/account_toggles.py, accounts/views/account_settings.py, course_management/context_processors.py, templates/core/_site_shell_head.html, templates/core/_site_shell_foot.html, templates/core/_design_system.html, course_platform_templates/accounts/account_settings.html, courses/static/settings_toggles.js, conftest.py

Also: design-5a body tags gained data-theme-preference (including templates/core/home.html body only); adoption hashes/inventory/migration counts; load/pull project-data mapping; identity inventory / reconciliation field name.

Exact commands and counts

make migrations-check
  → No changes detected

DJANGO_SETTINGS_MODULE=website.settings.test \
  uv run --frozen python manage.py test --noinput \
  accounts.tests_toggles accounts.tests_account_settings \
  accounts.tests.test_theme_preference_migration
  → 25 passed

make test
  → 2240 passed, 9 skipped

make verification-quality
  → terminology, portability, security, ruff, mypy (412 files),
    migrations-check, OpenAPI, management parity, deploy check,
    test-ci 531 passed

make verification-plan VERIFY_BASE_SHA=a8f7499… VERIFY_HEAD_SHA=a8f7499… \
  VERIFY_ISSUE=183 VERIFY_WORKTREE=issue-183-engineer

DTC_TEST_RUN_ID=… DJANGO_ALLOW_ASYNC_UNSAFE=true \
  pytest playwright_tests/test_theme_preference.py
  → 7 passed

pytest playwright_tests/test_legal_footer_125.py -k consent_keyboard \
        playwright_tests/test_home_events_design_parity.py -k dark
  → 6 passed (legacy darkMode seed + masthead toggle)

make verification-container
  → status pass (.tmp/verification/evidence/container-check.json)

make verification-run was started from this plan. Quality initially failed ruff format --check on conftest.py; that file was formatted, the plan was regenerated, and quality then passed. The official runner did not finish a single uninterrupted playwright envelope before the local timeout; focused Playwright evidence above is what was completed.

Broader pytest playwright_tests -m core still hits pre-existing failures that this diff does not change: homework breadcrumb height <= 24 vs the live 2.75rem target, article --page lavender vs a cream assertion, and strict heading-name collisions. They are outside this issue’s Theme contract.

Artifact / report paths

• Plan: .tmp/verification/verification-plan.json
• Selection: .tmp/verification/ci-selection.json and .tmp/verification/evidence/ci-selection.json
• Evidence dir: .tmp/verification/evidence/
• Container: .tmp/verification/evidence/container-check.json
• Engineer-only scratch shot (not independent evidence): .tmp/screenshots/issue-183/engineer-os-dark-home.png

Screenshot requirement

Required, pending_independent_tester. Render impact is true. The independent tester must capture desktop and mobile: light and dark of the homepage or a content page, and the settings page showing the three-state control in both themes. An engineer-produced screenshot is not independent evidence.

Behavior

• New accounts and anonymous visitors default to System.
• Existing dark_mode=True/False rows become Dark/Light so nobody’s rendered theme flips at deploy.
• Anonymous explicit choice lives in themePreference; darkMode remains readable.
• Authenticated System follows the OS at page load (no mid-session OS re-evaluation).
• Authenticated Light/Dark stay server-rendered with no script-dependent flash.
• Legacy flip endpoint and DARK_MODE stay in place for un-ported pages.

Limitations

• System is resolved at load only.
• Legacy dark_mode.js is unchanged and may still write darkMode on un-ported pages (explicit non-goal).
• Official make verification-run playwright/screenshot envelopes are incomplete; tester must recompute the plan from this frozen base/head/worktree and capture the graph-derived screenshots.
• Worktree is frozen uncommitted for tester review.

[alexeygrigorev]

QA Review

Observed 2026-08-19 in the frozen issue-183-engineer worktree.

Range and freeze

• Worktree: /home/alexey/.grok/worktrees/git-dtc-website/issue-183-engineer
• Branch: issue-183-engineer
• Base/head: a8f7499fc448f9a755fb24162856e6537b9aa663 / the same SHA
• Product state: 80 tracked paths modified and 4 untracked product files; no commit, push, or product-file edit was made by QA.
• No index lock or active writer process overlapped the target. The final HEAD and product diff remained unchanged.

Independent plan/graph

• Engineer plan SHA-256: b9591c89975a552e2859c292c174a7de08e6971d6c8d841f53bf5d78eb6c9756
• Tester plan: .tmp/verification/qa-183/verification-plan.json
• Tester raw plan SHA-256: fda67da420c6e848d8d65279b8809ac5229d83767ae580aa62883a5d3782aec1
• Normalized plan SHA-256 (volatile timestamps/environment evidence removed): 1eaf532830591cb03f5669e6381cec5c16761f08d47d1923e54f8fce2c132c4d, identical to the engineer plan.
• Graph SHA-256: 4127118b4467a75b40b8dbadc4050b5b2dc3762b292aca93cd9309a4593bca19, identical.
• Source manifest/tree: a2133ba05880a47dc1b76a141a6a05e58ca5a6f09ffc68be6900fc35c9d293d7 / d0a86e6ce38ccf3b97378331cc583793689f51aa.
• Render fingerprint/environment: ff54ca26e2eac4119d80a0b8fe3345d1ba7ea315f4ed7ea55ac88bd83a0ad5a5 / 62fa21213247d65c01dfa68fc441baab2da54c2726913ff61d3a157c5e0326b5.
• Profile: full; render impact: yes; required graph captures: /, /__verification_missing__, /courses, /studio/ at 1440×900 and 390×844.

Four-bucket disposition: rerun = selector, evidence_validation, quality, django, playwright, container, screenshots; reused = none; skipped = none; not_applicable = compatibility and content_invariants, exactly as planned.

Verification evidence

Passes:

• make verification-plan VERIFY_CONSUMER=tester ...: exit 0; both generated plans validate with ci.verification validate-plan.
• Focused Django command: 25 passed (accounts.tests_toggles, accounts.tests_account_settings, accounts.tests.test_theme_preference_migration).
• make migrations-check: no changes detected.
• make test-migrations: 17 passed.
• make test: 2,240 passed, 9 skipped.
• Quality primitives: lint passed; format check passed (553 files); mypy passed (412 files); Django/OpenAPI/management parity/deployment checks passed; make test-ci: 531 passed.
• make verification-container: exit 0; image build, collectstatic, and all migrations including accounts.0013_theme_preference completed.
• Issue-specific Playwright: test_theme_preference.py 7 passed.
• Legacy compatibility Playwright: 6 passed (darkMode seed and masthead dark-mode scenarios).

Required screenshot evidence:

• Graph-derived captures: 8/8 passed and inspected in .tmp/verification/qa-183/evidence/screenshots/screenshots.json (home, 404, courses, Studio sign-in; desktop/mobile). Each image showed the expected page, no debug/error page, and no horizontal overflow.
• Issue captures: 8/8 passed and inspected in .tmp/screenshots/issue-183-qa/screenshots.json: homepage light/dark desktop/mobile plus authenticated settings light/dark desktop/mobile. The settings images show the labelled System/Light/Dark group; synthetic account identity is redacted.

Failures/blockers:

• make verification-quality fails in security-check: pip-audit reports Django 6.0.7, PYSEC-2026-3717 / CVE-2026-15830, fixed in 6.0.8. pyproject.toml and uv.lock are unchanged from base, so this is a baseline dependency gate, not an issue-183 dependency change; it remains a required red gate.
• Required make test-playwright-core was stopped after five observed unrelated baseline failures at 17% (exit 130): test_homework_breadcrumb_target_spacing_ignores_closed_account_menu, test_the_article_page_renders_the_design_system_in_both_themes, test_registration_breadcrumb_matches_cmp_without_losing_target_spacing, test_copied_registration_count_zero_one_many_light_and_dark, and test_owner_login_distinct_surfaces_and_credential_lifecycle. The issue-specific theme and legacy suites passed; the long remaining browser leg was not allowed to continue after these concrete failures.

Acceptance criteria

1. Migration/default mapping: PASS — migration tests, migration check, full Django suite, and container migration.
2. Explicit server rendering and System pre-paint resolution: PASS — focused Playwright covers authenticated Light/Dark/System, anonymous OS-dark, reload/no-flash state.
3. Anonymous themePreference, legacy darkMode read, no new darkMode write: PASS — focused Playwright assertions.
4. Masthead explicit override and persistence: PASS — focused Playwright plus 6 legacy dark-mode tests.
5. Settings radio group, immediate save, invalid-value rejection: PASS — focused Django/Playwright and settings screenshots.
6. Legacy flip endpoint and 302/405 boundaries: PASS — focused Django tests.
7. Legacy DARK_MODE/course behavior: PASS — focused Django plus legacy Playwright coverage.
8. Light/dark color-scheme: PASS — focused Playwright state assertions and light/dark screenshots.
9. Playwright core coverage: issue-specific behavior PASS, but the required repository core gate is FAIL/incomplete because of the five observed unrelated failures above.
10. Tester screenshots: PASS — all 16 independent images are present, inspected, and marked pass in the two manifests above.

Terminal verdict

FAIL. Issue-specific theme behavior and required screenshots pass independently, but the tester gate cannot pass while the required security quality command is red and the required core Playwright gate has observed failures. No product fixes were applied.

[alexeygrigorev]

Product Acceptance

REJECT

I gated the exact uncommitted candidate in /home/alexey/.grok/worktrees/git-dtc-website/issue-183-engineer.

Candidate identity:

• Base and HEAD: a8f7499fc448f9a755fb24162856e6537b9aa663
• Worktree remains uncommitted and unchanged during this review; no commit, push, PR, or product-file edit was made.

Product result:

• The focused issue behavior is evidenced as passing: migration/default mapping, server and pre-paint theme resolution, anonymous themePreference with legacy darkMode read-only compatibility, masthead persistence, settings radio-group save and invalid-value rejection, endpoint 302/405 boundaries, legacy DARK_MODE behavior, and color-scheme.
• Tester evidence records 25 focused Django tests passed, 2,240 full Django tests passed with 9 skips, 17 migration tests passed, the issue-specific Playwright suite passed 7 tests, the legacy compatibility subset passed 6 tests, and the container check passed.
• All 8 issue-specific screenshots (homepage and settings, light/dark, desktop/mobile) were independently inspected and passed. The 8 graph-derived desktop/mobile captures also passed. The settings captures show the labelled System/Light/Dark group without visible overflow or an error/debug page.
• The tester plan and normalized engineer plan agree on the frozen base, graph, source tree, render fingerprint, and environment. All verification components are classified exactly once: no reuse and no skipped component; compatibility and content invariants are explicitly not applicable with recorded reasons.

The product implementation itself has no evidenced issue-specific failure. Acceptance is nevertheless blocked by two required repository gates:

1. make verification-quality is red in security-check: pip-audit finds Django 6.0.7 advisory PYSEC-2026-3717 / CVE-2026-15830, fixed in Django 6.0.8. pyproject.toml and uv.lock are unchanged from the base, so this is a baseline dependency/security blocker, not an issue-183 implementation failure. The pinned dependency must be brought to a supported fixed release, or the advisory must receive an explicit owner resolution, followed by a fresh quality/security gate.

2. The required make test-playwright-core gate is not green. QA observed five baseline failures and stopped the run at 17% (exit 130): test_homework_breadcrumb_target_spacing_ignores_closed_account_menu, test_the_article_page_renders_the_design_system_in_both_themes, test_registration_breadcrumb_matches_cmp_without_losing_target_spacing, test_copied_registration_count_zero_one_many_light_and_dark, and test_owner_login_distinct_surfaces_and_credential_lifecycle. QA attributes these to unrelated pre-existing contracts, and none is evidence of a theme-preference defect; however, the required core browser gate remains failed/incomplete and cannot be dismissed for product acceptance. Resolve/triage the baseline reds and rerun the complete required core suite.

Return this frozen candidate for the bounded gate rework above. Do not commit until the tester reports a passing terminal verdict and all required gates are green.

[alexeygrigorev]

Blocker audit update

Read-only audit completed 2026-08-21 against the frozen #183 engineer worktree and current origin/main.

The previously reported baseline security finding was Django 6.0.7, PYSEC-2026-3717 / CVE-2026-15830, fixed in Django 6.0.8. Current origin/main is 3909a48cbf009502f1284ac88782c764c7038a5f; its uv.lock pins Django 6.0.8, and make security-check passed with blocking_findings: [] and scanner exit 0.

The five previously reported Playwright failures were:

• test_homework_breadcrumb_target_spacing_ignores_closed_account_menu
• test_the_article_page_renders_the_design_system_in_both_themes
• test_registration_breadcrumb_matches_cmp_without_losing_target_spacing
• test_copied_registration_count_zero_one_many_light_and_dark
• test_owner_login_distinct_surfaces_and_credential_lifecycle

I reran those exact five functions on clean current origin/main: all 13 parameterized cases passed in 66.89s. The browser fixes from #193 and the Django update from #201 are reachable from this main.

Recommendation: keep the #183 delivery lane blocked at the lifecycle gate. The frozen candidate remains uncommitted at base/head a8f7499fc448f9a755fb24162856e6537b9aa663, while current origin/main is 57 commits ahead and shares changed paths with the candidate. Engineering should rebase/reconcile the candidate onto current origin/main, regenerate the verification plan, and hand it back for a fresh independent tester run of the complete required quality/core Playwright/screenshot gates before PM acceptance. No commit, merge, or close action is warranted from this audit.

[alexeygrigorev]

Software Engineer Report

READY_FOR_TESTER

Issue #183 was reconciled in the isolated worktree /home/alexey/git/dtc-website/.tmp/backlog-183-rebase-engineer from exact base 3909a48cbf009502f1284ac88782c764c7038a5f (origin/main). The worktree remains detached, uncommitted, unpushed, and unmerged. Base and reviewed HEAD are both 3909a48cbf009502f1284ac88782c764c7038a5f; the stale candidate source was a8f7499fc448f9a755fb24162856e6537b9aa663.

The candidate ported without product conflicts. The only three-way conflict was the generated _docs/adoption/course-platform/integration-patched-files.tsv; current-main ledger entries were retained and regenerated from pinned CMP source 98a235283904b4ef9ad29e196298540756cf1bcc. The manifest verification reports 768 copied files and 4 target-owned compatibility shims. There are no unresolved index conflicts.

Implementation preserves the groomed System/Light/Dark contract: one persisted theme_preference source, true→dark and false→light migration, anonymous themePreference storage with readable legacy darkMode fallback and no design-system writes to the legacy key, server-effective DARK_MODE, accessible settings radios and effective aria-pressed, prepaint OS resolution, no cookies, JS-off form submission, immediate authenticated saves, the legacy flip endpoint response, and legacy pages/dark_mode.js compatibility. A JS-off regression found during reconciliation was fixed so submitted theme radios save while omitted local account toggles remain preserved.

Verification plan

• Plan: .tmp/verification/verification-plan.json
• CI selection: .tmp/verification/ci-selection.json
• Plan SHA-256: 36dbd4be52d022da86ad9bc3b2fd88f1851a34c7b0cdfc805432162b4a7d2fe7
• Graph SHA-256: e0850384988f84551c0091e4fd5dd62e823038fa36f9d4d6fc0ea0ec6d207c2e
• Profile: full; reason: render_impact; changed paths: 85
• Risk flags: auth_security_privacy, dependency_toolchain, deployment_runtime, schema_migration, shared_runtime, test_infrastructure
• rerun: container, django, evidence_validation, playwright, quality, screenshots, selector
• reused: none
• skipped: none
• not_applicable: compatibility, content_invariants (empty impact closure)
• Plan-derived independent screenshots required: Chromium desktop/mobile for / (home), /__verification_missing__ (not-found), /courses (courses), and /studio/ (studio-sign-in), at 1440×900 and 390×844. Screenshots are pending the independent tester and must be stored under .tmp/screenshots/.

Evidence run

• uv run --frozen python scripts/verify_course_platform_adoption.py --write-patch-manifest — passed (768 copied files, 4 shims).
• Focused Django command covering toggles, settings, migration, enrollment profile, loader, migration support, adoption, and identity tests — 101 tests, OK; system check clean.
• DTC_TEST_RUN_ID=issue-183-engineer ... uv run --frozen pytest playwright_tests/test_theme_preference.py ... — 8 passed, including OS-dark anonymous, explicit persistence, legacy storage fallback, authenticated System/Dark, immediate settings save, JS-off settings save, and reload behavior.
• Legacy boundary command for test_legal_footer_125.py and test_home_events_design_parity.py — 2 passed, 21 deselected; legacy darkMode/keyboard surfaces remain green.
• make verification-quality — passed: security baseline, pip-audit (81 dependencies, 0 blocking findings), redaction canary/artifact scan, Ruff, format, mypy, migration drift, Django/deployment checks, and 594 CI tests.
• make verification-container VERIFY_CONTAINER_OUTPUT=.tmp/verification/evidence/container-check.json — passed; evidence: .tmp/verification/evidence/container-check.json (SHA-256 fc831d256f16f5e0b3bb312654d5b5ccb51f194d5a8e7c5e9644cf81bec9d1ae).
• make verification-plan ... — passed and independently validated; plan evidence is current at the stated base/head.
• git diff --check and cached diff check — passed.

The requested plan-bound make verification-run was started but cleanly stopped with Ctrl-C at the user-requested safe boundary after plan validation, while ci.runner was computing ci.evidence.worktree_manifest. Exit status was 130; no planned component command started and no runner component envelope or formal verification report was emitted. The exact command and boundary are preserved in .tmp/verification/verification-run-interrupted.log. The tester must independently rerun the plan-required components and produce the tester-final report; engineer-local command output is not independent evidence.

Tester instructions

1. Inspect the complete uncommitted diff and verify the frozen base/head and worktree before testing. Independently recompute the plan with VERIFY_CONSUMER=tester for the exact base/head and compare graph, plan, render captures, and every disposition.
2. Run the focused Django coverage, make test-playwright-core, and all plan-required fresh reruns. Validate the migration mapping, update allowlist/value rejection/response, flip endpoint compatibility, anonymous/authenticated persistence boundaries, no-cookie/privacy behavior, and no-JS full settings submission.
3. Exercise the browser contract at OS dark/light, System/Light/Dark, anonymous/authenticated, migrated member, keyboard-radio, and mobile states. Confirm legacy pages continue to use their existing server/DARK_MODE and dark_mode.js behavior.
4. Capture and inspect every plan-derived desktop/mobile screenshot under .tmp/screenshots/, plus the issue settings journey as needed. Report any broken/error/debug page or visual regression explicitly.
5. Leave the worktree uncommitted and do not push, merge, or close the issue.

Exact changed paths (85)

Makefile
_docs/adoption/course-platform/behavior-inventory.md
_docs/adoption/course-platform/integration-patched-files.tsv
_docs/audits/2026-08-14-course-platform-schema-data-inventory.md
_docs/design/design-5a.md
_docs/runbooks/account-reconciliation-mapping.example.json
accounts/forms.py
accounts/identity_inventory.py
accounts/models.py
accounts/reconciliation.py
accounts/templates/account/account_inactive.html
accounts/templates/account/password_reset.html
accounts/templates/account/password_reset_done.html
accounts/templates/account/password_reset_from_key.html
accounts/templates/account/password_reset_from_key_done.html
accounts/templates/account/signup.html
accounts/templates/account/signup_closed.html
accounts/templates/accounts/login.html
accounts/tests_account_settings.py
accounts/tests_account_settings_base.py
accounts/tests_toggles.py
accounts/views/account_settings.py
accounts/views/account_toggles.py
conftest.py
core/tests/test_course_platform_adoption.py
course_management/context_processors.py
course_platform_templates/account/logout.html
course_platform_templates/accounts/account_settings.html
course_platform_templates/socialaccount/authentication_error.html
course_platform_templates/socialaccount/connections.html
course_platform_templates/socialaccount/identity_conflict.html
course_platform_templates/socialaccount/login_cancelled.html
course_platform_templates/socialaccount/signup.html
courses/static/settings_toggles.js
courses/templates/courses/course.html
courses/templates/courses/course_list.html
courses/templates/courses/dashboard.html
courses/templates/courses/enrollment.html
courses/templates/courses/leaderboard.html
courses/templates/courses/leaderboard_complaint.html
courses/templates/courses/leaderboard_score_breakdown.html
courses/templates/courses/register.html
courses/templates/courses/user_wrapped.html
courses/templates/courses/wrapped.html
courses/templates/homework/homework.html
courses/templates/homework/stats.html
courses/templates/homework/submissions.html
courses/templates/index.html
courses/templates/projects/_base.html
courses/tests/test_load_project_data_script.py
playwright_tests/test_theme_preference.py
scripts/load_project_data.py
scripts/pull_project_data.py
scripts/tests/test_course_platform_schema_inventory.py
scripts/validate_course_platform_schema_inventory.py
templates/core/_design_system.html
templates/core/_site_shell_foot.html
templates/core/_site_shell_head.html
templates/core/home.html
templates/public/article_detail.html
templates/public/book_detail.html
templates/public/catalogue_fixture.html
templates/public/collection_hub.html
templates/public/event_detail.html
templates/public/events.html
templates/public/person_detail.html
templates/public/podcast_detail.html
templates/public/podcast_hub.html
templates/public/text_page.html
templates/public/wiki_detail.html
templates/public/wiki_graph.html
templates/public/wiki_hub.html
templates/public/wiki_search.html
templates/public/wiki_special.html
templates/review/course_cohort.html
templates/review/docs_detail.html
templates/review/docs_home.html
templates/review/faq_detail.html
templates/review/faq_home.html
templates/review/registration_preview.html
templates/studio/base.html
test_support/tests/test_migrations.py
accounts/migrations/0013_theme_preference.py
accounts/services/theme.py
accounts/tests/test_theme_preference_migration.py

[alexeygrigorev]

QA Review

FAIL — verification incomplete

Independent tester review of the exact reconciled candidate stopped at the user-requested clean boundary. The candidate is not green and must not advance to PM acceptance.

Identity and plan

• Worktree: /home/alexey/git/dtc-website/.tmp/backlog-183-rebase-tester
• Base: 3909a48cbf009502f1284ac88782c764c7038a5f
• Candidate HEAD: 3909a48cbf009502f1284ac88782c764c7038a5f plus the uncommitted candidate tree
• Candidate scope: 85 paths (81 tracked edits + 4 untracked additions); tracked diff SHA-256 062fd106d102460af434ad97f7755f901de7ab1f879a802d218ba46f3b2453d1
• Tester plan: .tmp/verification/issue-183-tester/verification-plan.json
• Plan SHA-256: 36dbd4be52d022da86ad9bc3b2fd88f1851a34c7b0cdfc805432162b4a7d2fe7
• Graph SHA-256: e0850384988f84551c0091e4fd5dd62e823038fa36f9d4d6fc0ea0ec6d207c2e
• Recomputed plan matches the engineer plan exactly: full profile, render impact, eight Chromium desktop/mobile captures, no reuse, compatibility/content invariants not applicable.

Commands and results

• DJANGO_SETTINGS_MODULE=website.settings.test uv run --frozen python manage.py test --noinput accounts.tests_toggles accounts.tests_account_settings accounts.tests.test_theme_preference_migration — 26 passed, clean system check.
• DJANGO_SETTINGS_MODULE=website.settings.test DJANGO_ALLOW_ASYNC_UNSAFE=true uv run --frozen pytest playwright_tests/test_theme_preference.py -v — 8 passed.
• Legacy boundary: ... uv run --frozen pytest playwright_tests/test_home_events_design_parity.py -k test_home_events_and_detail_match_cmp_composition -v — 2 failed, 5 deselected. Both desktop and mobile cases fail at /events after the test removes only legacy darkMode: expected body.dark-mode count 0, actual count 1. This is a candidate-facing compatibility failure.
• make verification-quality — PASS: security baseline/vulnerability/artifact scans (0 blocking findings), lint, format (595 files), mypy (439 files), migration drift, Django/OpenAPI/parity/deploy checks, and 594 CI tests passed. Security artifacts are under .tmp/security/.
• make test-migrations — 17 passed, clean system check.
• Required make test-playwright-core — selected 211 tests; the same two test_home_events_and_detail_match_cmp_composition cases failed. It was then stopped with Ctrl-C at the requested clean boundary, exit 130, while the partial run was at 76%. It has no pytest terminal summary; this is not green evidence.

Missing required gates/evidence

• The plan-bound make verification-run was not started after the stop instruction; there are no component envelopes or formal verification-report.json.
• Required full plan reruns are therefore missing: full Django, plan-bound evidence validation, full browser component completion, and container verification.
• The eight plan-derived screenshots (home, not-found, courses, Studio sign-in × desktop/mobile) were not captured. Only .tmp/screenshots/issue-183/engineer-os-dark-home.png exists and was visually inspected as an expected dark homepage; it cannot satisfy the complete screenshot gate.
• Retained logs/evidence:
  • .tmp/verification/issue-183-tester/manual/focused-django.log (SHA-256 31a9e49caef50e517ac4f3b51f852139eb6390e42dbce245476122f731713a2c)
  • .tmp/verification/issue-183-tester/manual/theme-playwright.log (SHA-256 99e1e520f7809154144e9deabcc88d67979a770bfb92a8fb348c22c1870a77b2)
  • .tmp/verification/issue-183-tester/manual/legacy-playwright.log (SHA-256 9139913624ef2acbd888a044e871566bc3d735cbb8f0e706465870e9df397546)
  • .tmp/verification/issue-183-tester/manual/core-playwright.log (SHA-256 bfac9152198d961e798942968fd13c23593b9cd72f8f66891350c7d9e9368601; partial, no terminal summary)
  • .tmp/verification/issue-183-tester/manual/verification-quality.log (SHA-256 168ff35ea435d8331e532c2cd198326185b370b53fc2577e69322ea0f4c05014)
  • .tmp/verification/issue-183-tester/manual/test-migrations.log (SHA-256 080762b276e311145dbc0d210883a939caa84fcc1f3bd01b3bfcbf2265493464)
  • .tmp/verification/issue-183-tester/tester-final-incomplete.md

No implementation file was edited; no commit, push, merge, or issue close was performed.

[alexeygrigorev]

Software Engineer Rework Report

READY_FOR_TESTER

Base / head / scope

• Worktree: /home/alexey/git/dtc-website/.tmp/backlog-183-rebase-engineer
• Base: 3909a48cbf009502f1284ac88782c764c7038a5f
• Candidate head: 3909a48cbf009502f1284ac88782c764c7038a5f plus the uncommitted candidate tree
• The original 85-path candidate was preserved. This rework adds exactly one tracked path,
  playwright_tests/test_home_events_design_parity.py; current scope is 86 paths (82 tracked
  edits and 4 untracked additions). Tracked diff SHA-256:
  01079285506bc5eadeb2744d15ecb4e3dd7a853854116ff4a0a599000f6a30cf.
• No commit, push, merge, or issue close was performed. The root checkout and tester worktree
  were not touched.

Exact fix

The parity flow clicks the masthead pill on /, which correctly persists the new anonymous
themePreference=dark choice. Removing only legacy darkMode cannot reset that explicit new
preference, so /events remained dark. The helper now clears both supported anonymous storage
keys before its light-state assertion. With neither key present, the preference is System,
which resolves to Light under the test browser's default media preference. Existing assertions
were retained; the product shell was not weakened or changed.

The groomed compatibility contract remains intact: themePreference explicit Light/Dark wins
and persists; legacy darkMode is still read as Light/Dark only when the new key is absent; and
the site never writes darkMode.

Verification

• Focused legacy boundary before fix: 2 failed (desktop/mobile), 5 deselected.
• DJANGO_SETTINGS_MODULE=website.settings.test DJANGO_ALLOW_ASYNC_UNSAFE=true uv run --frozen pytest playwright_tests/test_home_events_design_parity.py -k test_home_events_and_detail_match_cmp_composition -v — 2 passed, 5 deselected.
• DJANGO_SETTINGS_MODULE=website.settings.test DJANGO_ALLOW_ASYNC_UNSAFE=true uv run --frozen pytest playwright_tests/test_theme_preference.py -v — 8 passed.
• DJANGO_SETTINGS_MODULE=website.settings.test uv run --frozen python manage.py test --noinput accounts.tests_toggles accounts.tests_account_settings accounts.tests.test_theme_preference_migration — 26 passed, clean system check.
• make verification-quality — PASS: security checks, Ruff, format, mypy, migration/OpenAPI/system checks, and 594 CI tests passed.
• git diff --check 3909a48 and cached diff check — PASS.

Verification plan

• Plan: .tmp/verification/issue-183-rework/verification-plan.json
• Plan SHA-256: c28b1c310ad0d653df0fe7271ccd4a847c799578c90190880939f580da72d397
• Graph SHA-256: e0850384988f84551c0091e4fd5dd62e823038fa36f9d4d6fc0ea0ec6d207c2e
• Source-tree manifest SHA-256: 62bd4fa7afea6a10b8c651377e8561c06ac2cb92dedd27a6f209a884fad94b5e
• Full profile, render impact, and 8 plan-derived Chromium desktop/mobile captures. The plan
  marks full Django, full browser, container, quality, evidence, selector, and screenshot
  components for fresh rerun; compatibility and content invariants are not applicable. The
  independent tester must complete those plan-bound gates and screenshot inspection.

The worktree is left uncommitted and frozen for tester review.