From 70bad93cdeb4fe114e3202fff7b3b091c8bcbc84 Mon Sep 17 00:00:00 2001
From: Eric Boehs <eric@boehs.com>
Date: Sat, 29 Aug 2026 22:16:08 -0500
Subject: [PATCH 1/2] feat: pure black dark mode with blue story links

Dark mode rendered every link white, because UIkit's .uk-light sets
`a { color: #fff }`. That erased the distinction between a story title
and ordinary text. It also sets `.uk-text-primary { color: #fff
!important }`, which silently removed the blue high-score highlight, so
a 328-point story looked identical to a 55-point one.

Story links and the score highlight are now #58a6ff. Measured against
the new background it is 8.3:1, clearing WCAG AAA; UIkit's own #1e87f0
only reaches 5.8:1 and fails AA outright on the previous #222.

Background is pure black so OLED pixels switch off rather than draw dark
grey. That made the #DDD thread borders glaring -- 15:1 against the page,
louder than the text beside them -- so they drop to #2a2a2a, with the
hover border reusing the link blue.

The dark palette is now gated behind .hn-dark, which the script adds.
Previously the dark background came from the media query alone while the
text colour came from .uk-light via JS, so with JS disabled the page
rendered #666 text on a #222 background: a contrast ratio of 1.9:1.
It now falls back to the light palette, which is at least readable.

The script moves to <head> and runs synchronously so the background is
set before first paint instead of flashing white, and it listens for
media-query changes rather than re-checking twice a second for the life
of the tab.

Verified with Chrome over the DevTools protocol, emulating each colour
scheme and reading computed styles: dark gives rgb(0,0,0) background
with rgb(88,166,255) links and score, borders rgb(42,42,42); with script
execution disabled the html element carries no class and the background
stays white.
---
 tests/app_test.rb | 14 +++++++++++
 views/layout.erb  | 62 +++++++++++++++++++++++++++++++++++------------
 2 files changed, 60 insertions(+), 16 deletions(-)

diff --git a/tests/app_test.rb b/tests/app_test.rb
index f98b56c..789f995 100644
--- a/tests/app_test.rb
+++ b/tests/app_test.rb
@@ -318,6 +318,20 @@ def test_ordinary_urls_still_render
 
   # --- caching --------------------------------------------------------------
 
+  # The dark palette is gated on .hn-dark, which only JS adds. If that gate is
+  # ever removed, dark mode renders #666 text on a black background.
+  def test_dark_mode_styles_are_scoped_so_the_page_survives_without_js
+    create_item id: 1, title: 'A', score: 100
+
+    get '/'
+    body = last_response.body
+
+    assert_includes body, 'prefers-color-scheme: dark'
+    assert_includes body, 'html.hn-dark, html.hn-dark body { background-color: #000 }'
+    # Driven by a media-query listener rather than a timer.
+    assert_includes body, "addEventListener('change', applyScheme)"
+  end
+
   def test_homepage_sends_cache_validators
     create_item id: 1, title: 'A', score: 100
 
diff --git a/views/layout.erb b/views/layout.erb
index 57f5d6e..9cdbb0c 100644
--- a/views/layout.erb
+++ b/views/layout.erb
@@ -40,10 +40,55 @@
         a { color: #0d0d0d; }
       }
 
+      /* Dark mode is applied by the script in <head>, which adds .hn-dark to
+         <html> and UIkit's .uk-light to <body>. Scoping the dark palette to
+         .hn-dark means that with JS disabled the page stays on the readable
+         light palette rather than dark text on a dark background. */
       @media (prefers-color-scheme: dark) {
-        html { background-color: rgb(34, 34, 34) }
+        /* Pure black rather than #222 so OLED pixels switch off entirely. */
+        html.hn-dark, html.hn-dark body { background-color: #000 }
+
+        /* .uk-light paints every link #fff, which erases the difference
+           between a story title and ordinary text. #58a6ff measures 8.3:1 on
+           black (WCAG AAA); UIkit's own #1e87f0 only reaches 5.8:1. */
+        .hn-dark .uk-light .story a,
+        .hn-dark .uk-light table a { color: #58a6ff }
+
+        /* Visited stories stay dimmed, the way HN does it. This has to follow
+           the rule above: the two selectors have equal specificity. */
+        .hn-dark .uk-light table a:visited { color: #999 }
+
+        /* .uk-light also forces .uk-text-primary to #fff !important, which
+           loses the high-score highlight completely. */
+        .hn-dark .uk-light .uk-text-primary { color: #58a6ff !important }
+
+        /* #DDD thread borders measure 15:1 on black, louder than the text
+           they sit beside. */
+        .hn-dark .uk-comment-list li { border-left-color: #2a2a2a }
+        .hn-dark .uk-comment-list li:hover { border-left-color: #58a6ff }
       }
     </style>
+
+    <script>
+      // In <head> and synchronous so the dark background is set before first
+      // paint; deferring this flashes a white page. Replaces a setInterval
+      // that re-checked the media query twice a second for the life of the tab.
+      (function () {
+        var query = window.matchMedia('(prefers-color-scheme: dark)')
+
+        function applyScheme () {
+          document.documentElement.classList.toggle('hn-dark', query.matches)
+          if (document.body) document.body.classList.toggle('uk-light', query.matches)
+        }
+
+        applyScheme()
+        document.addEventListener('DOMContentLoaded', applyScheme)
+
+        // Safari below 14 only has the deprecated addListener.
+        if (query.addEventListener) query.addEventListener('change', applyScheme)
+        else if (query.addListener) query.addListener(applyScheme)
+      })()
+    </script>
   </head>
   <body>
     <div class="uk-container uk-container-small uk-margin-bottom">
@@ -53,21 +98,6 @@
 
       <%= yield %>
 
-      <!-- Enable dark mode -->
-      <script>
-        function toggleDarkMode() {
-          if (window.matchMedia("(prefers-color-scheme: dark)").matches) {
-            document.body.classList.add('uk-light')
-          } else {
-            document.body.classList.remove('uk-light')
-          }
-        }
-
-        toggleDarkMode()
-
-        setInterval(toggleDarkMode, 500)
-      </script>
-
       <% if ENV['GA_TRACKING_ID'] %>
         <script async src="https://www.googletagmanager.com/gtag/js?id=<%= ENV['GA_TRACKING_ID'] %>"></script>
         <script>

From fae33d3f60776007c368d660923479f624e63618 Mon Sep 17 00:00:00 2001
From: Eric Boehs <eric@boehs.com>
Date: Sat, 29 Aug 2026 22:23:14 -0500
Subject: [PATCH 2/2] fix: address review - detail page title, stale CSS behind
 ETags

The story detail page title stayed white. Its link sits in an <h3>, so
neither the .story nor the table selector reached it -- and that page is
exactly the one the change was asked for. Confirmed in the browser at
rgb(255,255,255); the heading now carries .story and reads rgb(88,166,255)
like the listing.

Validators were built only from database rows, so a template change alone
kept serving 304 to anyone holding an older ETag. A busy listing recovers
on the next worker write, but a settled thread never changes, so it could
serve the old stylesheet indefinitely. A digest of the templates now feeds
the key: touching a view changes TEMPLATE_VERSION and every ETag with it.

Corrected a wrong comment: a:visited is a class-level component more
specific than the rule above it, so it wins on specificity, not source
order. Also softened the claim that white links are indistinguishable
from body text -- uk-light body text is translucent white, so the
difference is small rather than absent.

Loosened the dark-mode test, which asserted exact CSS and JS source and
would have failed on reformatting while passing on broken rendering. It
now checks only that the dark background cannot apply without the
scripted class, and says so.
---
 app.rb            | 13 ++++++++++++-
 tests/app_test.rb | 30 ++++++++++++++++--------------
 views/layout.erb  | 13 ++++++-------
 3 files changed, 34 insertions(+), 22 deletions(-)

diff --git a/app.rb b/app.rb
index f2b27a4..e77e043 100644
--- a/app.rb
+++ b/app.rb
@@ -9,6 +9,7 @@
 Dotenv.load '.env.local', '.env'
 
 require 'logger'
+require 'digest'
 require 'active_record'
 require './models/item'
 
@@ -47,6 +48,14 @@ def self.log_device
   # be escaped.
   SAFE_URL_SCHEMES = %w[http https].freeze
 
+  # Validators are computed from database rows, so a template change alone
+  # would keep serving 304 to anyone holding an older ETag until a story
+  # happened to change -- indefinitely for a settled thread. Folding a digest
+  # of the templates into the key retires those cached copies on deploy.
+  TEMPLATE_VERSION = Digest::SHA256.hexdigest(
+    Dir[File.join(__dir__, 'views', '*.erb')].sort.map { |f| File.read f }.join
+  )[0, 12]
+
   helpers do
     def h(value)
       Rack::Utils.escape_html value.to_s
@@ -79,7 +88,9 @@ def safe_url(value, item_id: nil)
     def cache_for(records)
       cache_control :public, :must_revalidate, max_age: 30
       newest = records.filter_map(&:updated_at).max
-      etag Digest::SHA256.hexdigest("#{newest&.to_f}-#{records.map(&:id).join(',')}")
+      etag Digest::SHA256.hexdigest(
+        "#{TEMPLATE_VERSION}-#{newest&.to_f}-#{records.map(&:id).join(',')}"
+      )
     end
   end
 
diff --git a/tests/app_test.rb b/tests/app_test.rb
index 789f995..14d73e7 100644
--- a/tests/app_test.rb
+++ b/tests/app_test.rb
@@ -275,6 +275,22 @@ def test_comment_html_is_still_rendered
     assert_includes last_response.body, '<a href="https://x.test">this</a>'
   end
 
+  # Structural guard, not a rendering guarantee: the dark palette is gated on
+  # .hn-dark, which only the script adds. If that gate is ever dropped while
+  # the background rule stays, dark mode paints #666 text onto black. Actual
+  # colours are verified out of band with a real browser.
+  def test_dark_palette_is_gated_on_the_scripted_class
+    create_item id: 1, title: 'A', score: 100
+
+    get '/'
+    body = last_response.body
+
+    assert_includes body, 'prefers-color-scheme: dark'
+    assert_includes body, 'hn-dark'
+    refute_match(/@media \(prefers-color-scheme: dark\)\s*\{\s*html\s*\{/, body,
+                 'dark background must not apply without the scripted class')
+  end
+
   def test_javascript_urls_are_not_rendered_as_links
     create_item id: 1, title: 'Bad', score: 100, url: 'javascript:alert(1)'
 
@@ -318,20 +334,6 @@ def test_ordinary_urls_still_render
 
   # --- caching --------------------------------------------------------------
 
-  # The dark palette is gated on .hn-dark, which only JS adds. If that gate is
-  # ever removed, dark mode renders #666 text on a black background.
-  def test_dark_mode_styles_are_scoped_so_the_page_survives_without_js
-    create_item id: 1, title: 'A', score: 100
-
-    get '/'
-    body = last_response.body
-
-    assert_includes body, 'prefers-color-scheme: dark'
-    assert_includes body, 'html.hn-dark, html.hn-dark body { background-color: #000 }'
-    # Driven by a media-query listener rather than a timer.
-    assert_includes body, "addEventListener('change', applyScheme)"
-  end
-
   def test_homepage_sends_cache_validators
     create_item id: 1, title: 'A', score: 100
 
diff --git a/views/layout.erb b/views/layout.erb
index 9cdbb0c..898a6a8 100644
--- a/views/layout.erb
+++ b/views/layout.erb
@@ -48,14 +48,14 @@
         /* Pure black rather than #222 so OLED pixels switch off entirely. */
         html.hn-dark, html.hn-dark body { background-color: #000 }
 
-        /* .uk-light paints every link #fff, which erases the difference
-           between a story title and ordinary text. #58a6ff measures 8.3:1 on
-           black (WCAG AAA); UIkit's own #1e87f0 only reaches 5.8:1. */
+        /* .uk-light paints every link #fff, leaving a story title nearly
+           indistinguishable from the translucent white body text around it.
+           #58a6ff restores the link affordance and measures 8.3:1 on black
+           (WCAG AAA); UIkit's own #1e87f0 only reaches 5.8:1. */
         .hn-dark .uk-light .story a,
         .hn-dark .uk-light table a { color: #58a6ff }
 
-        /* Visited stories stay dimmed, the way HN does it. This has to follow
-           the rule above: the two selectors have equal specificity. */
+        /* Visited links in the listing stay dimmed, the way HN does it. */
         .hn-dark .uk-light table a:visited { color: #999 }
 
         /* .uk-light also forces .uk-text-primary to #fff !important, which
@@ -71,8 +71,7 @@
 
     <script>
       // In <head> and synchronous so the dark background is set before first
-      // paint; deferring this flashes a white page. Replaces a setInterval
-      // that re-checked the media query twice a second for the life of the tab.
+      // paint; deferring this flashes a white page.
       (function () {
         var query = window.matchMedia('(prefers-color-scheme: dark)')