diff --git a/docs/cms.md b/docs/cms.md
index 119be3f..59bef8c 100644
--- a/docs/cms.md
+++ b/docs/cms.md
@@ -73,6 +73,26 @@ orange, `>15min` red) and offers one-tap state transitions.
 Today the monitor + KDS poll every 5–8 s. SSE / Nostr push is on
 the roadmap.
 
+### Dark-mode color discipline
+
+Quasar's pale `bg-{color}-1` utility classes (e.g. `bg-orange-1`,
+`bg-red-1`, `bg-amber-1`) pair fine with the default light theme
+but render **white-on-cream** under LNbits' dark theme — the
+q-card otherwise inherits the body's light text color. The KDS
+cards pin a dark text class alongside every pale background so
+the card stays legible regardless of theme:
+
+```js
+if (order.status === 'ready')  return 'bg-amber-1 text-grey-9'
+if (ageSec > 900)              return 'bg-red-1 text-grey-9'
+if (ageSec > 300)              return 'bg-orange-1 text-grey-9'
+return ''   // theme-default branch keeps q-card's own text color
+```
+
+Any future surface that ages / escalates with `bg-{color}-1` must
+do the same. Never assume a pale background "just works" on dark
+theme.
+
 ## Settings
 
 `settings.html` saves restaurant fields via
diff --git a/static/js/kds.js b/static/js/kds.js
index bc0980d..ab4f0cc 100644
--- a/static/js/kds.js
+++ b/static/js/kds.js
@@ -25,10 +25,16 @@ window.app = Vue.createApp({
     },
     cardClass(order) {
       // Visually escalate as orders age. >5min = highlight; >15min = alarm.
+      //
+      // Pair every pale `bg-{color}-1` with an explicit dark text color
+      // — otherwise on LNbits dark mode the q-card inherits light text
+      // and renders white-on-cream, which is unreadable. The non-
+      // highlighted branch (default theme) returns '' so the q-card
+      // keeps its theme-aware defaults.
       const ageSec = (Date.now() - new Date(order.time).getTime()) / 1000
-      if (order.status === 'ready') return 'bg-amber-1'
-      if (ageSec > 900) return 'bg-red-1'
-      if (ageSec > 300) return 'bg-orange-1'
+      if (order.status === 'ready') return 'bg-amber-1 text-grey-9'
+      if (ageSec > 900) return 'bg-red-1 text-grey-9'
+      if (ageSec > 300) return 'bg-orange-1 text-grey-9'
       return ''
     },
     async fetchActive() {