# Add a Dark Mode Toggle to a VitePress Blog With a Custom Theme

Yes. An agent moves a Tailwind VitePress theme from system-only dark mode to a persisted toggle using VitePress's own appearance script, builds it and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-dark-mode/vitepress/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how dark styles reach the page today before it adds a button, because a custom VitePress theme can follow the system, a class, or both. In a blog like vuejs/blog, `package.json` has `vitepress` ^1.3.4, `vue` ^3.5.0-beta.3, `tailwindcss` ^3.4.10, `@tailwindcss/typography`, `feed` and `gray-matter`, with `pnpm@9.8.0` as the package manager and `dev`, `build`, `serve` and `preview` scripts. `.vitepress/config.ts` sets `cleanUrls: true`, Twitter and icon `head` entries, a Fathom analytics script and `buildEnd: genFeed`, and says nothing about `appearance`, so VitePress's default of `true` applies. `.vitepress/theme/index.ts` exports only a `Layout`, with no default theme imported, and `postcss.config.js` configures Tailwind inline with `content: ['./.vitepress/theme/**/*.vue']` and the typography plugin, and no `darkMode` setting, so Tailwind's `dark:` variants follow `prefers-color-scheme`. The components already carry those variants everywhere: `Layout.vue` wraps the page in `antialiased dark:bg-slate-900` and gives the nav links `dark:text-white` and `dark:hover:text-gray-200`; `Home.vue` and `Article.vue` use `dark:text-white`, `dark:divide-slate-200/5`, `dark:text-gray-300` and `prose dark:prose-invert`; and `style.css` has one `@media (prefers-color-scheme: dark)` block for inline code colours plus a `.vp-code span { color: var(--shiki-dark, inherit) }` rule for code blocks. So the blog is dark when the operating system is, and a reader cannot choose.

VitePress already ships the part people usually write by hand. With `appearance` left on, it injects an inline script before render that reads the `vitepress-theme-appearance` key from local storage and puts a `.dark` class on `<html>`, so there is no flash on load, and `useData()` hands a theme `isDark`, a `Ref<boolean>`, that tracks that class. The agent therefore changes Tailwind rather than the components: `darkMode: 'class'` in the inline Tailwind config in `postcss.config.js`, which makes every existing `dark:` variant key off the `.dark` class VitePress manages instead of the media query, so none of the `dark:` utilities in the three components move. The one `@media (prefers-color-scheme: dark)` block in `style.css` becomes a `.dark` selector so inline code follows the toggle too, and the Shiki rule needs no change because VitePress sets `--shiki-dark` under the same class.

The toggle itself is a small component. The agent writes `.vitepress/theme/AppearanceToggle.vue`, a `<button>` with an `aria-label` that reads `isDark` from `useData()` and flips it on click, and places it in `Layout.vue`'s nav after the RSS link with the same `text-sm` and separator dot the other links use, so the header's rhythm holds. Writing to `isDark` is what VitePress's own default theme does for its switch, and the write updates the `.dark` class and the local storage key through the appearance handling, so the choice survives a reload and the next page. Because `Layout.vue` is the only layout and `NotFound.vue` renders inside it, the 404 page gets the toggle for free. The `vp-raw` class on the RSS link is left as it is.

Then it builds and looks. In its own sandbox the agent runs `pnpm install` and `pnpm build`, which also runs `genFeed` into `.vitepress/dist/feed.rss`, then `pnpm preview` and opens the home page and a post such as `posts/vue-3-5.md` in its browser: it emulates a dark system scheme and confirms the page is light until the toggle is pressed and dark after, reloads to confirm the choice persists through the inline script with no flash, and screenshots both states on both pages. It also checks the `prose dark:prose-invert` article body and an inline code span in each state, since those are where the Tailwind and CSS changes meet, and runs a build-size comparison of the main CSS asset before and after to show the class strategy added nothing measurable.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a dark mode toggle to this VitePress blog, which has a custom Tailwind theme and no default theme. Read package.json, .vitepress/config.ts, .vitepress/theme/index.ts, Layout.vue, Home.vue, Article.vue, NotFound.vue, style.css and postcss.config.js first, and list every place dark styles come from today. Keep VitePress's appearance setting on and use its inline script and the isDark ref from useData rather than writing your own storage code. Switch Tailwind to the class dark mode strategy so the existing dark variants follow the html class, and rewrite the one prefers-color-scheme block in style.css to the same class. Add a small toggle component to the nav in Layout.vue in the style of the existing links. Run pnpm install and pnpm build, serve the build, open the home page and one post in the browser with a dark system scheme, confirm the toggle and that the choice persists across a reload, screenshot light and dark on both pages, compare the main CSS asset size before and after, and open a pull request with the screenshots and the measurements.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

A pull request that changes `postcss.config.js`, `.vitepress/theme/style.css` and `Layout.vue`, adds `AppearanceToggle.vue`, and touches no post. The description lists where dark styles came from before, shows the toggle in the nav, and carries four screenshots from the sandbox browser, light and dark on the home page and on a post, plus the CSS asset sizes before and after and a note that reload kept the choice.

The repository deploys through Vercel with `vercel.json`, so the pull request gets a preview deployment from that integration rather than a GitHub workflow, and a reviewer opens it to try the toggle. They decide whether the default for a first visit should follow the system, which the pull request keeps, or start light, which is one `appearance` value in `config.ts`.

## Run it on every reader request for a theme switch

A team that runs several VitePress sites with custom themes starts one run per repository from its own server: a `POST /o/{org}/sessions` each, with this prompt as `input`, the repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads that site's theme, so a site that already uses the default theme's `VPSwitchAppearance` gets a note and no change, and a site on Tailwind 4 gets the `@custom-variant dark` line instead of a `darkMode` key.

The key's `webhook_url` receives `run.completed` for each run, with the `session_url` to read the pull request link from, and the Vercel preview on each pull request is where the team looks at the result.

## Why run it on Rush?

A dark mode toggle is a common request with a common failure: a theme that writes its own local storage code and flashes light on every load, or a Tailwind config that switches to the class strategy while one stylesheet still listens to the media query, so code spans stay light in a dark page. The agent reads the three components and the stylesheet, uses the script VitePress already injects, and checks the result in a real browser with a dark system scheme, reloads included, so the pull request shows the toggle working rather than describing it.

Every command and screenshot stays with the run, and the pull request quotes the build and the asset sizes. The same change across a team's sites costs no more attention than one, because each run reads that site's theme and opens its own pull request.

## Frequently asked questions

### Why not write a toggle that sets a class and saves to local storage?

VitePress already does that with its `appearance` option: an inline script restores the stored choice before the first paint and `useData().isDark` reflects it, so a hand-written version would duplicate it and risk a flash on load. The component only reads and writes `isDark`.

### Do the existing dark: classes in the components change?

No. Switching Tailwind to `darkMode: 'class'` makes every existing `dark:` variant follow the `.dark` class on `<html>` instead of the media query, so `Layout.vue`, `Home.vue` and `Article.vue` keep their classes. The one `@media (prefers-color-scheme: dark)` block in `style.css` is rewritten to the same class.

### What does a first-time visitor see?

The system scheme, as today, because VitePress's appearance script falls back to `prefers-color-scheme` when nothing is stored. Pressing the toggle stores a choice that wins from then on; a team that prefers a light default changes the `appearance` value in `config.ts`.

### Does the RSS feed or the analytics script change?

No. `genFeed` still runs at `buildEnd` and writes `feed.rss`, and the Fathom script in `head` is untouched. The pull request shows the feed file in the build output to confirm the build end hook still ran.

## More VitePress jobs

- [Add Dependabot to a VitePress Site](https://getrush.ai/run/add-dependabot/vitepress/)
- [Add a Build Check for a VitePress Docs Site on Every Pull Request](https://getrush.ai/run/add-docs-build-check/vitepress/)
- [Add Draft Posts to a VitePress Blog](https://getrush.ai/run/add-draft-posts/vitepress/)

## The same job on other stacks

- [Add Dark Mode to a Vue App](https://getrush.ai/run/add-dark-mode/vue/)
- [Add Dark Mode to a Zola Theme](https://getrush.ai/run/add-dark-mode/zola/)
- [Add Dark Mode to an Angular App](https://getrush.ai/run/add-dark-mode/angular/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
