diff --git a/apps/desktop/src/renderer/src/assets/base.css b/apps/desktop/src/renderer/src/assets/base.css
index 473755017..abacc0d8f 100644
--- a/apps/desktop/src/renderer/src/assets/base.css
+++ b/apps/desktop/src/renderer/src/assets/base.css
@@ -2098,6 +2098,13 @@ del.bn-inline-content {
   --sidebar-border: #d9d5ce;
   --sidebar-ring: var(--tint);
   --sidebar-muted: #b5b0a6;
+  /* The sidebar's de-emphasized small-text colour: section and tag-group
+     headings, item counts, the tag list's show-more control — anything
+     carrying real information at 10-11px, which WCAG AA treats as small text
+     (4.5:1). Separate from --sidebar-muted, which also colors chevrons and
+     decorative icon buttons where the extra weight would be too loud.
+     5.07:1 on --sidebar, 5.07:1 on --muted (the row hover surface). */
+  --sidebar-section-heading: #6b6459;
   --sidebar-terracotta: var(--tint);
   --sidebar-text-folder: #3d3a35;
   --sidebar-text-child: #5c5850;
@@ -2116,6 +2123,8 @@ del.bn-inline-content {
   --sidebar-border: #e9e9e7;
   --sidebar-ring: var(--tint);
   --sidebar-muted: #b0afab;
+  /* 5.16:1 on --sidebar, 5.06:1 on --muted. See the :root block. */
+  --sidebar-section-heading: #6b6966;
   --sidebar-terracotta: var(--tint);
   --sidebar-text-folder: #37352f;
   --sidebar-text-child: #6b6966;
@@ -2134,6 +2143,8 @@ del.bn-inline-content {
   --sidebar-border: #333333;
   --sidebar-ring: var(--tint);
   --sidebar-muted: #6b6b6b;
+  /* 6.42:1 on --sidebar, 6.01:1 on --muted. See the :root block. */
+  --sidebar-section-heading: #9d9d9d;
   --sidebar-terracotta: var(--tint);
   --sidebar-text-folder: #c5c0b8;
   --sidebar-text-child: #9a958d;
@@ -2241,6 +2252,7 @@ del.bn-inline-content {
   --color-sidebar-border: var(--sidebar-border);
   --color-sidebar-ring: var(--sidebar-ring);
   --color-sidebar-muted: var(--sidebar-muted);
+  --color-sidebar-section-heading: var(--sidebar-section-heading);
   --color-sidebar-terracotta: var(--sidebar-terracotta);
   --color-sidebar-text-folder: var(--sidebar-text-folder);
   --color-sidebar-text-child: var(--sidebar-text-child);
diff --git a/apps/desktop/src/renderer/src/components/sidebar-section.contrast.test.tsx b/apps/desktop/src/renderer/src/components/sidebar-section.contrast.test.tsx
new file mode 100644
index 000000000..17adef421
--- /dev/null
+++ b/apps/desktop/src/renderer/src/components/sidebar-section.contrast.test.tsx
@@ -0,0 +1,75 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { render, screen } from '@testing-library/react'
+
+import { SidebarSection } from './sidebar-section'
+import { SidebarProvider } from '@/components/ui/sidebar'
+import {
+  AA_SMALL_TEXT,
+  THEMES,
+  assertSmallTextContrast,
+  contrastRatio,
+  resolveColor
+} from '@tests/utils/contrast'
+
+// The section heading renders at 11px and its collapsed item count at 10px,
+// which WCAG AA treats as small text and holds to 4.5:1. jsdom has no cascade
+// and no layout, so the ratios are computed from the literal hex in base.css —
+// see tests/utils/contrast.ts.
+
+function renderSection(props: Partial<React.ComponentProps<typeof SidebarSection>> = {}) {
+  return render(
+    <SidebarProvider>
+      <SidebarSection id="contrast" label="Notes" {...props}>
+        <div>child</div>
+      </SidebarSection>
+    </SidebarProvider>
+  )
+}
+
+function headerButton(): HTMLElement {
+  renderSection()
+  return screen.getByRole('button', { name: /^Notes section/ })
+}
+
+// `SidebarSection` seeds `isExpanded` from `sidebar-section-<id>-expanded` and
+// writes it back on every toggle, and jsdom keeps localStorage for the whole
+// file. A stored value silently outranks the `defaultExpanded={false}` the
+// count test depends on, so clear it rather than let test order decide.
+beforeEach(() => {
+  localStorage.clear()
+})
+
+describe('sidebar section contrast', () => {
+  it('defines the heading token in every sidebar theme', () => {
+    for (const selector of THEMES) {
+      expect(resolveColor(selector, '--sidebar-section-heading')).toMatch(/^#[0-9a-f]{6}$/i)
+      expect(resolveColor(selector, '--sidebar')).toMatch(/^#[0-9a-f]{6}$/i)
+    }
+  })
+
+  it.each(THEMES)('clears WCAG AA for small text in %s', (selector) => {
+    const heading = resolveColor(selector, '--sidebar-section-heading')
+    const background = resolveColor(selector, '--sidebar')
+
+    expect(contrastRatio(heading, background)).toBeGreaterThanOrEqual(AA_SMALL_TEXT)
+  })
+
+  it('paints the header with the heading token', () => {
+    expect(headerButton().className.split(/\s+/)).toContain('text-sidebar-section-heading')
+  })
+
+  it('never swaps the header to a colour below AA on hover', () => {
+    // The sidebar paints `bg-sidebar`; the header has no background of its own.
+    expect(() => assertSmallTextContrast(headerButton().className, ['--sidebar'])).not.toThrow()
+  })
+
+  it('holds the collapsed item count to AA too', () => {
+    // The count is the only thing left saying how much a collapsed section
+    // hides, so it is informational text, not decoration.
+    renderSection({ defaultExpanded: false, totalCount: 7 })
+    const count = screen.getByText('(7)')
+
+    expect(() => assertSmallTextContrast(count.className, ['--sidebar'])).not.toThrow()
+    expect(count.className.split(/\s+/)).toContain('text-sidebar-section-heading')
+  })
+})
diff --git a/apps/desktop/src/renderer/src/components/sidebar-section.tsx b/apps/desktop/src/renderer/src/components/sidebar-section.tsx
index c3eb9fb6e..d9135ff01 100644
--- a/apps/desktop/src/renderer/src/components/sidebar-section.tsx
+++ b/apps/desktop/src/renderer/src/components/sidebar-section.tsx
@@ -123,8 +123,12 @@ export const SidebarSection = ({
               'flex flex-1 min-w-0 cursor-pointer items-center gap-1.5 px-2 py-1 h-6 shrink-0',
               'text-[11px] leading-3.5 font-medium tracking-[0.04em]',
               "font-['DM_Sans',system-ui,sans-serif]",
-              'text-sidebar-muted hover:text-sidebar-foreground',
-              'transition-colors focus-visible:outline-none'
+              // Resting colour only. `hover:text-sidebar-foreground` used to live
+              // here, and on the paper sidebar that is 3.18:1 — under the 4.5:1 AA
+              // floor for 11px text — so the heading lost its guarantee exactly
+              // while being pointed at. The chevron fading in carries the affordance.
+              'text-sidebar-section-heading',
+              'focus-visible:outline-none'
             )}
             aria-expanded={isExpanded}
             aria-controls={contentId}
@@ -135,7 +139,11 @@ export const SidebarSection = ({
             <SectionChevron expanded={isExpanded} />
 
             {!isExpanded && totalCount !== undefined && totalCount > 0 && (
-              <span className="text-sidebar-muted/60 tabular-nums text-[10px] leading-3">
+              // The count is the only thing left telling you how much a
+              // collapsed section hides, so it is informational text, not
+              // decoration: `--sidebar-muted` at 60% was 1.43:1 on the paper
+              // sidebar. The heading token carries it at 5.07:1.
+              <span className="text-sidebar-section-heading tabular-nums text-[10px] leading-3">
                 ({totalCount})
               </span>
             )}
diff --git a/apps/desktop/src/renderer/src/components/sidebar/sidebar-tag-list.contrast.test.tsx b/apps/desktop/src/renderer/src/components/sidebar/sidebar-tag-list.contrast.test.tsx
new file mode 100644
index 000000000..b22a91426
--- /dev/null
+++ b/apps/desktop/src/renderer/src/components/sidebar/sidebar-tag-list.contrast.test.tsx
@@ -0,0 +1,85 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { render, screen } from '@testing-library/react'
+
+import { SidebarTagList } from './sidebar-tag-list'
+import { assertSmallTextContrast } from '@tests/utils/contrast'
+
+// The tag list lives inside `bg-sidebar`. Its group headings render at 10px and
+// its show-more control at 11px, both of which WCAG AA treats as small text and
+// holds to 4.5:1. jsdom has no cascade and no layout, so the ratios come from
+// the literal hex in base.css — see tests/utils/contrast.ts.
+
+vi.mock('@memry/i18n/renderer', () => ({
+  useT: () => ({
+    t: (key: string, params?: Record<string, unknown>) =>
+      String(params?.count ?? key.split('.').at(-1) ?? key)
+  })
+}))
+
+const TAGS = [
+  { tag: 'alpha', count: 4, color: 'blue', icon: null, sortOrder: 0 },
+  { tag: 'beta', count: 2, color: 'green', icon: null, sortOrder: 1 }
+]
+
+vi.mock('@/hooks/use-notes-query', () => ({
+  useNoteTagsQuery: () => ({ tags: TAGS, isLoading: false, error: null })
+}))
+
+vi.mock('@/hooks/use-sidebar-navigation', () => ({
+  useSidebarNavigation: () => ({ openSidebarItem: vi.fn() })
+}))
+
+vi.mock('@/hooks/use-tag-categories', () => ({
+  useTagCategories: () => ({
+    categories: [{ id: 'work', name: 'Work', sortOrder: 0, tags: TAGS }],
+    uncategorized: [],
+    isLoading: false,
+    error: null
+  })
+}))
+
+// `SidebarTagList` seeds its expanded set and its sort order from localStorage
+// and writes the expanded set back on mount, and jsdom keeps localStorage for
+// the whole file. A stored collapsed category hides every element these tests
+// query, and a stored sort order changes which tag survives `maxVisible={1}`,
+// so clear it rather than let test order decide.
+beforeEach(() => {
+  localStorage.clear()
+})
+
+// maxVisible below the group size is what makes the show-more control render.
+function renderTagList(): void {
+  render(<SidebarTagList maxVisible={1} />)
+}
+
+describe('sidebar tag list contrast', () => {
+  it('holds the tag-group heading to AA at rest and on hover', () => {
+    renderTagList()
+    const heading = screen.getByRole('button', { name: 'collapse' })
+
+    // The heading swaps its own background to `bg-muted` on hover, so it has to
+    // clear the floor against both surfaces.
+    expect(() => assertSmallTextContrast(heading.className, ['--sidebar', '--muted'])).not.toThrow()
+    expect(heading.className.split(/\s+/)).toContain('text-sidebar-section-heading')
+  })
+
+  it('holds the show-more control to AA at rest and on hover', () => {
+    renderTagList()
+    // The mocked translator echoes the interpolated count, so "1" is the label
+    // of "show 1 more".
+    const showMore = screen.getByRole('button', { name: '1' })
+
+    expect(() => assertSmallTextContrast(showMore.className, ['--sidebar'])).not.toThrow()
+    expect(showMore.className.split(/\s+/)).toContain('text-sidebar-section-heading')
+  })
+
+  it('holds the per-tag note count to AA', () => {
+    renderTagList()
+    // The count only fades in while its row is hovered, and that same hover
+    // paints the row `bg-muted`, so `--muted` is the only surface it sits on.
+    const count = screen.getByText('4')
+
+    expect(() => assertSmallTextContrast(count.className, ['--muted'])).not.toThrow()
+    expect(count.className.split(/\s+/)).toContain('text-sidebar-section-heading')
+  })
+})
diff --git a/apps/desktop/src/renderer/src/components/sidebar/sidebar-tag-list.tsx b/apps/desktop/src/renderer/src/components/sidebar/sidebar-tag-list.tsx
index b0bdf12b2..1c56c6f55 100644
--- a/apps/desktop/src/renderer/src/components/sidebar/sidebar-tag-list.tsx
+++ b/apps/desktop/src/renderer/src/components/sidebar/sidebar-tag-list.tsx
@@ -260,7 +260,10 @@ function TagTreeItem({
           </ContextMenuContent>
         </ContextMenu>
 
-        <span className="ms-auto pe-2.5 text-[10px] text-muted-foreground/40 tabular-nums opacity-0 group-hover:opacity-100 transition-opacity">
+        {/* The note count is information, not chrome, and 10px is small text
+            under WCAG AA. `--muted-foreground` at 40% was 1.95:1 on the row's
+            hover background; the sidebar heading token holds 5.06:1 there. */}
+        <span className="ms-auto pe-2.5 text-[10px] text-sidebar-section-heading tabular-nums opacity-0 group-hover:opacity-100 transition-opacity">
           {node.totalCount}
         </span>
       </div>
@@ -526,10 +529,16 @@ export function SidebarTagList({
 
             return (
               <div key={group.id} className="flex flex-col gap-0.5">
+                {/* A category heading, so it takes the same token as every
+                    other sidebar section heading. `--muted-foreground` at 70%
+                    was 3.62:1 (paper) and 2.85:1 (white) at 10px, under the
+                    4.5:1 AA floor for small text. The colour no longer changes
+                    on hover — `bg-muted` carries the affordance, and the token
+                    clears AA on that surface too. */}
                 <button
                   type="button"
                   onClick={() => handleToggle(`${CATEGORY_KEY_PREFIX}${group.id}`)}
-                  className="flex items-center gap-1 px-2 py-0.5 rounded-md text-[10px] font-semibold uppercase tracking-wide text-muted-foreground/70 hover:text-foreground hover:bg-muted transition-colors"
+                  className="flex items-center gap-1 px-2 py-0.5 rounded-md text-[10px] font-semibold uppercase tracking-wide text-sidebar-section-heading hover:bg-muted transition-colors"
                   aria-label={isGroupExpanded ? t('action.collapse') : t('action.expand')}
                 >
                   {isGroupExpanded ? (
@@ -556,7 +565,13 @@ export function SidebarTagList({
                       <button
                         type="button"
                         onClick={() => toggleShowAllForGroup(group.id)}
-                        className="rounded-sm py-0.5 px-2 ms-6 text-[11px] font-medium leading-3.5 text-sidebar-muted hover:text-sidebar-foreground transition-colors text-start"
+                        // 11px is small text under WCAG AA. `--sidebar-muted`
+                        // was 1.87:1 on the paper sidebar and hovering made it
+                        // 3.18:1 — still under 4.5:1. This is a control rather
+                        // than a heading, so unlike the section headings it
+                        // keeps a hover colour: `--sidebar-primary` raises the
+                        // ratio (15.2:1 paper) instead of lowering it.
+                        className="rounded-sm py-0.5 px-2 ms-6 text-[11px] font-medium leading-3.5 text-sidebar-section-heading hover:text-sidebar-primary transition-colors text-start"
                       >
                         {showAllForGroup
                           ? t('action.showLess')
diff --git a/apps/desktop/tests/utils/contrast.ts b/apps/desktop/tests/utils/contrast.ts
new file mode 100644
index 000000000..894398ce6
--- /dev/null
+++ b/apps/desktop/tests/utils/contrast.ts
@@ -0,0 +1,189 @@
+/**
+ * WCAG contrast helpers for renderer tests.
+ *
+ * jsdom has no cascade and no layout, so a render can never prove a contrast
+ * ratio. The palette is literal hex in base.css though, so tests read the theme
+ * blocks straight from source and do the arithmetic themselves.
+ */
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** WCAG AA floor for small text (under 18.66px, or 14px bold). */
+export const AA_SMALL_TEXT = 4.5
+
+/** Selector of every theme block that carries a full palette. */
+export const THEMES = [':root', '.white', '.dark'] as const
+export type ThemeSelector = (typeof THEMES)[number]
+
+// Vitest's cwd is apps/desktop.
+const BASE_CSS = join(process.cwd(), 'src/renderer/src/assets/base.css')
+
+/**
+ * One custom-property map per theme. base.css declares each theme across
+ * several flat blocks (`@layer base` for the app palette, a later top-level
+ * block for the sidebar palette), so declarations are merged in document order
+ * — last wins, as the cascade would have it. `.white` and `.dark` are classes on
+ * the root element, so `:root` still applies underneath them and seeds both.
+ */
+function readPalettes(): Map<ThemeSelector, Map<string, string>> {
+  const css = readFileSync(BASE_CSS, 'utf8').replace(/\/\*[\s\S]*?\*\//g, '')
+  const palettes = new Map<ThemeSelector, Map<string, string>>(
+    THEMES.map((selector) => [selector, new Map<string, string>()])
+  )
+
+  for (const [, rawSelector, body] of css.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
+    const selector = rawSelector.trim() as ThemeSelector
+    const palette = palettes.get(selector)
+    if (!palette) continue
+    for (const [, name, value] of body.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/g)) {
+      palette.set(name, value.trim())
+    }
+  }
+
+  const root = palettes.get(':root') as Map<string, string>
+  for (const selector of THEMES) {
+    if (selector === ':root') continue
+    palettes.set(selector, new Map([...root, ...(palettes.get(selector) as Map<string, string>)]))
+  }
+
+  return palettes
+}
+
+const PALETTES = readPalettes()
+
+/** Resolve a custom property to a hex literal, following `var(--x)` chains. */
+export function resolveColor(selector: ThemeSelector, name: string): string {
+  const palette = PALETTES.get(selector) as Map<string, string>
+  let value = palette.get(name)
+  for (let hops = 0; value?.startsWith('var(') && hops < 4; hops++) {
+    value = palette.get(value.slice(4, -1).split(',')[0].trim())
+  }
+  if (!value || !/^#[0-9a-f]{6}$/i.test(value)) {
+    throw new Error(
+      `${selector} ${name} does not resolve to a hex colour (got ${value ?? 'nothing'})`
+    )
+  }
+  return value
+}
+
+export function relativeLuminance(hex: string): number {
+  const [r, g, b] = [1, 3, 5].map((offset) => {
+    const channel = parseInt(hex.slice(offset, offset + 2), 16) / 255
+    return channel <= 0.03928 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4
+  })
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b
+}
+
+export function contrastRatio(a: string, b: string): number {
+  const [lighter, darker] = [relativeLuminance(a), relativeLuminance(b)].sort((x, y) => y - x)
+  return (lighter + 0.05) / (darker + 0.05)
+}
+
+// `text-*` utilities that set something other than a colour, so no ratio
+// applies: sizes (`text-[11px]`, `text-xs`), alignment and wrapping. An
+// arbitrary value that is not a length — `text-[#6b6459]` — is still a colour.
+const NON_COLOR_TEXT =
+  /^text-(\[\d|(xs|sm|base|lg|[2-9]?xl|start|end|left|right|center|justify|balance|pretty|wrap|nowrap|clip|ellipsis)$)/
+
+function isColorTextUtility(utility: string): boolean {
+  return utility.startsWith('text-') && !NON_COLOR_TEXT.test(utility)
+}
+
+/**
+ * Every class in `className` that repaints the text behind a state variant,
+ * however the variant is spelled. Plain `hover:text-…` is only one shape:
+ * `group-hover/section:text-…`, `peer-hover:text-…`, `dark:hover:text-…` and
+ * `[&:hover]:text-…` all repaint on hover too, and a guard that only matched
+ * the first shape would wave every other one through.
+ */
+export function stateTextClasses(className: string): string[] {
+  return className.split(/\s+/).filter((cls) => {
+    const lastColon = cls.lastIndexOf(':')
+    if (lastColon === -1) return false
+    if (!isColorTextUtility(cls.slice(lastColon + 1))) return false
+    return cls
+      .slice(0, lastColon)
+      .split(':')
+      .some((variant) => /hover|focus|active/.test(variant))
+  })
+}
+
+/** The unconditional text colour class, if the element sets one. */
+export function restingTextClass(className: string): string | null {
+  return (
+    className
+      .split(/\s+/)
+      .filter((cls) => !cls.includes(':') && isColorTextUtility(cls))
+      .at(-1) ?? null
+  )
+}
+
+/** Composite `foreground` at `alpha` over `background`, both `#rrggbb`. */
+function blend(foreground: string, background: string, alpha: number): string {
+  const channel = (offset: number): string => {
+    const f = parseInt(foreground.slice(offset, offset + 2), 16)
+    const b = parseInt(background.slice(offset, offset + 2), 16)
+    return Math.round(f * alpha + b * (1 - alpha))
+      .toString(16)
+      .padStart(2, '0')
+  }
+  return `#${channel(1)}${channel(3)}${channel(5)}`
+}
+
+/**
+ * Hex a `text-…` utility actually paints: a literal `text-[#rrggbb]`, else a
+ * theme token, composited over `background` when the class carries Tailwind's
+ * `/NN` opacity modifier (`text-sidebar-muted/60` is not `--sidebar-muted`).
+ */
+export function textUtilityColor(selector: ThemeSelector, cls: string, background: string): string {
+  const [token, alpha] = cls
+    .slice(cls.lastIndexOf(':') + 1)
+    .replace(/^text-/, '')
+    .split('/')
+  const literal = /^\[(#[0-9a-f]{6})\]$/i.exec(token)
+  const hex = literal ? literal[1] : resolveColor(selector, `--${token}`)
+  return alpha === undefined ? hex : blend(hex, background, Number(alpha) / 100)
+}
+
+/**
+ * Assert that `className` clears AA for small text on every one of
+ * `backgroundTokens`, in every theme, both at rest and under any state variant
+ * — and that no state variant *lowers* the ratio it rests at. Throws naming the
+ * class, theme and background that failed.
+ */
+export function assertSmallTextContrast(className: string, backgroundTokens: string[]): void {
+  const resting = restingTextClass(className)
+  if (!resting) throw new Error(`no resting text colour class in "${className}"`)
+
+  for (const selector of THEMES) {
+    for (const backgroundToken of backgroundTokens) {
+      const background = resolveColor(selector, backgroundToken)
+      const restingRatio = contrastRatio(
+        textUtilityColor(selector, resting, background),
+        background
+      )
+      if (restingRatio < AA_SMALL_TEXT) {
+        throw new Error(
+          `${resting} on ${backgroundToken} in ${selector} is ${restingRatio.toFixed(3)}:1, under AA ${AA_SMALL_TEXT}:1`
+        )
+      }
+
+      for (const stateClass of stateTextClasses(className)) {
+        const stateRatio = contrastRatio(
+          textUtilityColor(selector, stateClass, background),
+          background
+        )
+        if (stateRatio < AA_SMALL_TEXT) {
+          throw new Error(
+            `${stateClass} on ${backgroundToken} in ${selector} is ${stateRatio.toFixed(3)}:1, under AA ${AA_SMALL_TEXT}:1`
+          )
+        }
+        if (stateRatio < restingRatio) {
+          throw new Error(
+            `${stateClass} on ${backgroundToken} in ${selector} drops contrast from ${restingRatio.toFixed(3)}:1 to ${stateRatio.toFixed(3)}:1`
+          )
+        }
+      }
+    }
+  }
+}
diff --git a/apps/docs/src/contribute/testing.md b/apps/docs/src/contribute/testing.md
index 555058354..1bf29948a 100644
--- a/apps/docs/src/contribute/testing.md
+++ b/apps/docs/src/contribute/testing.md
@@ -68,6 +68,37 @@ pnpm --filter @memry/desktop seed:vault
 - Time-sensitive workflow tests should use dates relative to the current run instead of fixed
   calendar dates, so snooze/reminder assertions do not expire as CI time moves forward.
 
+### Renderer State Leaks Between Tests In A File
+
+`tests/setup-dom.ts` calls `cleanup()` and `tests/setup.ts` resets mocks, but **neither clears
+`localStorage`**. The renderer project runs `pool: 'threads'` with `isolate: true`, so jsdom is
+fresh per _file_ and shared by every test _inside_ it. A component that seeds UI state on mount
+and writes it back therefore leaks into later tests in the same file — `SidebarSection`
+(`sidebar-section-<id>-expanded`) and `SidebarTagList` (`sidebar-tags-expanded`,
+`sidebar-tags-sort`) both do.
+
+The failure looks like a component bug, not pollution: the element simply is not in the tree, or
+a query matches a different one. Add `beforeEach(() => localStorage.clear())` to any such file,
+and prove the pin is load-bearing by pre-seeding the key and asserting the element disappears.
+
+### Contrast Assertions
+
+jsdom has no cascade and no layout, so rendering can never prove a contrast ratio. The palette is
+literal hex in `src/renderer/src/assets/base.css`, so `tests/utils/contrast.ts` reads the theme
+blocks (`:root`, `.white`, `.dark`) straight from source and does the arithmetic:
+
+```ts
+import { assertSmallTextContrast } from '@tests/utils/contrast'
+
+// Throws naming the class, theme and background that failed.
+assertSmallTextContrast(element.className, ['--sidebar', '--muted'])
+```
+
+It checks every theme, understands Tailwind's `/NN` opacity modifier
+(`text-sidebar-muted/60` is not `--sidebar-muted`), and fails on any state variant that repaints
+the text below the WCAG AA floor for small text — or merely below where it rested. Because it
+reads the CSS at module load, a concurrent edit to `base.css` changes results mid-run.
+
 ## E2E (Playwright)
 
 ```bash
diff --git a/docs/DESIGN_TOKENS.md b/docs/DESIGN_TOKENS.md
index 47b149300..214b86767 100644
--- a/docs/DESIGN_TOKENS.md
+++ b/docs/DESIGN_TOKENS.md
@@ -188,12 +188,21 @@ Dark mode uses lighter, more legible variants.
 | `--sidebar-border`             | `#d9d5ce`                   | `#e9e9e7`                   | `#333333`                | `border-sidebar-border`           |
 | `--sidebar-ring`               | `var(--tint)`               | `var(--tint)`               | `var(--tint)`            | `ring-sidebar-ring`               |
 | `--sidebar-muted`              | `#b5b0a6`                   | `#b0afab`                   | `#6b6b6b`                | `text-sidebar-muted`              |
+| `--sidebar-section-heading`    | `#6b6459`                   | `#6b6966`                   | `#9d9d9d`                | `text-sidebar-section-heading`    |
 | `--sidebar-terracotta`         | `var(--tint)`               | `var(--tint)`               | `var(--tint)`            | `bg-sidebar-terracotta`           |
 | `--sidebar-text-folder`        | `#3d3a35`                   | `#37352f`                   | `#c5c0b8`                | `text-sidebar-text-folder`        |
 | `--sidebar-text-child`         | `#5c5850`                   | `#6b6966`                   | `#9a958d`                | `text-sidebar-text-child`         |
 | `--sidebar-dot-inactive`       | `#d9d5ce`                   | `#e3e2e0`                   | `#444444`                | `bg-sidebar-dot-inactive`         |
 | `--sidebar-surface`            | `rgba(0,0,0,0.04)`          | `rgba(0,0,0,0.03)`          | `#2a2a2a`                | `bg-sidebar-surface`              |
 
+**`--sidebar-section-heading`** is the only sidebar token with a contrast floor. It is the sidebar's de-emphasised **small-text** colour: anything in the sidebar that carries real information at 10–11px takes it, because WCAG AA treats that size as small text and holds it to 4.5:1. The token is kept separate from `--sidebar-muted` — that one also colours chevrons and decorative icon buttons, where darkening would be too loud. Current users: `SidebarSection`'s heading and its collapsed item count, and in `SidebarTagList` the tag-group headings, the show-more control, and the per-tag note count.
+
+Measured against each theme's own `--sidebar` in `base.css` (`#efefe9` / `#f9f8f7` / `#1a1a1a`): **5.07:1**, **5.16:1**, **6.42:1**. Two of those users sit on `--muted` instead (`#efefe9` / `#f7f6f3` / `#202020`), because their row paints `hover:bg-muted` while the text is visible: **5.07:1**, **5.06:1**, **6.01:1**.
+
+Headings take no hover colour: `--sidebar-foreground`, the old hover target, is 3.18:1 on the warm sidebar, and the tokens that would clear the floor are the emphasis colours — too loud for a static label. The chevron fading in, or the row's `bg-muted`, carries the affordance instead. The one exception is the tag list's show-more **control**, where `hover:text-sidebar-primary` _raises_ the ratio (15.22:1 / 11.56:1 / 13.84:1).
+
+`sidebar-section.contrast.test.tsx` and `sidebar/sidebar-tag-list.contrast.test.tsx` recompute every one of these ratios from this CSS via `tests/utils/contrast.ts` and fail under 4.5 — including any state variant (`hover:`, `group-hover/name:`, `focus:`, …) that repaints the text below the floor, or merely below where it rested.
+
 ---
 
 ## Graph View