docs: correct stale UI comments on error handling and colour tokens

- mood-insights-sections: the docblock claimed the sections render nothing
  on a failed read; the rest region now surfaces a QueryErrorRow with retry
- band-tokens / coverage-meter: the raw dracula primitives now carry their
  own AA-tuned light overrides, so the no-override claim no longer holds;
  the band still rides the semantic token for concept cohesion
- medication-card-body: drop the pb-2.5 header claim the header no longer sets
- modules-section: the body follows the card gap rhythm, not an mt-4 margin

src/components/insights/derived/band-tokens.ts

@@ -12,10 +12,12 @@
  * `--destructive: #cb3a2a`) precisely because straight Dracula
  * green/orange on a white `--card` clears only ~1.1–1.5:1 — under AA.
  * Painting the band off the semantic token means every score surface
- * tracks that light-mode correction automatically, in both themes; the
- * raw `--dracula-*` primitives do NOT carry a light override. A
- * green/yellow/red band is the one semantic the whole v1.10 score
- * language extends.
+ * tracks that light-mode correction automatically, in both themes. The
+ * raw `--dracula-*` primitives now carry their own AA-tuned light
+ * overrides too (globals.css `:root.light`), so chart code that passes
+ * `var(--dracula-*)` references is theme-safe; the band still rides the
+ * semantic token because a green/yellow/red band is the one semantic the
+ * whole v1.10 score language extends.
  */
 
 export type ScoreBand = "green" | "yellow" | "red";

src/components/insights/derived/coverage-meter.tsx

@@ -66,11 +66,12 @@ export interface CoverageMeterProps {
  * Dot tint per confidence band. Points at the *semantic* feedback tokens
  * (`--success` / `--warning` / `--destructive`), not the raw `--dracula-*`
  * primitives, so the dots track the AA-safe `:root.light` overrides on the
- * white card — straight `bg-dracula-yellow` cleared barely 1.1:1 on white
- * and read near-invisible. The four bands collapse onto the three semantic
- * severities (medium + low both ride the caution `--warning`); the lit-dot
- * count + the percent label carry the medium↔low distinction, never colour
- * alone.
+ * white card. (The raw primitives now carry their own light overrides in
+ * globals.css as well, so this is concept cohesion with the score language
+ * rather than the only contrast-safe path it once was.) The four bands
+ * collapse onto the three semantic severities (medium + low both ride the
+ * caution `--warning`); the lit-dot count + the percent label carry the
+ * medium↔low distinction, never colour alone.
  */
 const BAND_DOT_CLASS: Record<DerivedConfidenceBand, string> = {
   high: "bg-success",

src/components/insights/mood/mood-insights-sections.tsx

@@ -72,8 +72,12 @@ const MoodInsightsBreakdowns = dynamic(
  * Reads the pre-computed aggregate bundle from `/api/mood/insights` (cheap
  * cached server read, no LLM) and paints the calendar and the assessment
  * itself, handing the payload to the deferred breakdown module for everything
- * under them. Renders nothing while loading / on error / on an empty data set
- * so the page degrades gracefully to the line chart.
+ * under them. On an empty data set the sections render nothing so the page
+ * degrades to the line chart; a failed read is not silent, though — the "rest"
+ * region surfaces a `QueryErrorRow` with retry (§6) and shows the loading
+ * skeleton while fetching. The heatmap / assessment regions stay invisible
+ * during load and error so the page never stacks three frames (see the
+ * region split below).
  */
 
 /**

src/components/medications/card-parts/medication-card-body.tsx

@@ -250,9 +250,9 @@ export function MedicationCardBody({
       //
       // v1.16.12 — the shadcn card primitive's airy `gap-4 md:gap-6` between
       // header and content read as a wide gulf below the category badge before
-      // the first content line; tightened to a uniform `gap-3` here (the
-      // header keeps its own `pb-2.5`) so the name / class / next-intake block
-      // reads as one tight stack without touching the shared primitive.
+      // the first content line; tightened to a uniform `gap-3` here so the
+      // name / class / next-intake block reads as one tight stack without
+      // touching the shared primitive.
       //
       // v1.29.x — `highlighted` adds a transient ring (mirrors
       // `<DocumentCard highlighted>`) for the Today digest's deep-link

src/components/settings/modules-section.tsx

@@ -202,7 +202,7 @@ export function ModulesSection() {
   return (
     <SettingsCard>
       {/* The "what this section does" hint rides the header's standard
-          description slot; the body follows at the settings-wide mt-4
+          description slot; the body follows on the card's gap-based
           header→content rhythm instead of the former mb-2/mb-3 one-offs. */}
       <SettingsCardHeader
         icon={Blocks}