Raw view: Dark Mode Testing

No invisible, zero-width, or bidi-control characters detected.

---
name: dark-mode-testing
description: >-
  Toggle between light and dark mode in the harness's browser tool, screenshot
  both states, and flag missing token mappings or contrast issues. Use after
  theme or styling changes, or when the user asks to verify dark mode support.
user-invocable: true
disable-model-invocation: true
---

# Dark Mode Testing

Verify that dark mode renders correctly by toggling the theme and comparing.

## Runtime requirements

- A browser tool that can run JavaScript in the page, plus a running dev server. See the tool mapping in `visual-qa-testing`.
- Works fully in local agents. Cloud Agents need the app runnable in the VM with browser access.
- If the environment cannot run the app or open a browser, say so and skip.

## Workflow

1. **Find how the project switches theme** before toggling. Check for a `dark` class on `<html>` (Tailwind), a `data-theme` attribute, a `prefers-color-scheme` media query, or a theme provider. `AGENTS.md` may say.
2. **Screenshot light mode** on the changed route.
3. **Toggle dark mode** using the matching method:
   - Class: `document.documentElement.classList.add("dark")`
   - Attribute: `document.documentElement.setAttribute("data-theme", "dark")`
   - Media query: emulate `prefers-color-scheme: dark` (Cursor: `browser_cdp` with `Emulation.setEmulatedMedia`; Claude Code: `resize_window` with `colorScheme: "dark"`)
   - UI: find the theme toggle in the accessibility tree and click it
4. **Screenshot dark mode.**
5. **Inspect both screenshots and the accessibility tree** for:
   - White flashes: hardcoded light backgrounds instead of theme tokens
   - Invisible text: text color matching the dark background
   - Missing borders: light-only border colors that vanish on dark
   - Contrast: body text below 4.5:1 against its background
   - Hardcoded colors: `#fff`, `#000`, `white`, `black` in inline styles
   - Images: logos or icons with no dark variant
   - Shadows that disappear on dark backgrounds
   - Form inputs that keep light backgrounds
6. **Restore the original theme** when finished.
7. **Report:**

   ```
   Dark mode: /settings
     Light: OK
     Dark issues:
       - Header logo: white logo invisible on dark bg (needs dark variant)
       - Card borders: border-gray-200 invisible → add dark:border-gray-700
   ```

Fix each issue you introduced and re-test. Tailwind pattern: `bg-white dark:bg-slate-900`, `text-gray-900 dark:text-gray-100`, `border-gray-200 dark:border-gray-700`. For non-Tailwind projects, fix the CSS custom property or `[data-theme]` selector instead.

## Related skills

- `responsive-testing` — dark mode at multiple viewport sizes
- `visual-qa-testing` — general post-change QA