What the agent does
The agent starts from how the site handles colour today. In a blog like 11ty/eleventy-base-blog, css/index.css defines the palette as custom properties on :root (--background-color: #fff, --text-color from --color-gray-90, three link colours) and overrides them inside one @media (prefers-color-scheme: dark) block that sets --background-color: #15202b and lighter link colours. css/message-box.css repeats the pattern for its own --color-message-box, and _includes/layouts/post.njk inlines prism-okaidia.css from node_modules/prismjs, a dark code theme used in both schemes. So the site already follows the system setting and has no way for a reader to pick the other one.
It then reads how CSS and scripts reach the page, because this site bundles both. eleventy.config.js registers a css bundle and a js bundle with addBundle, each with bundleHtmlContentFromSelector, which means every <style> and <script> in a template is lifted into a per-page bundle unless it carries eleventy:ignore. _includes/layouts/base.njk includes css/index.css into a <style>, prints the bundle with {% getBundle "css" %}, and loads the script bundle at the end of <body> from {% getBundleFileUrl "js" %}. That last detail matters: a theme script that runs only after the body loads would paint the light palette first, so the small script that applies the saved choice must stay inline in <head> with eleventy:ignore, and only the toggle's click handler belongs in the bundle.
The change is three files. In css/index.css the dark values move out of the media query into a [data-theme="dark"] rule on html, and the media query becomes :root:not([data-theme="light"]) so a reader with no saved choice still gets the system scheme; css/message-box.css gets the same treatment. In base.njk, a <script eleventy:ignore> in <head> reads localStorage.theme and sets data-theme before the first paint, and a <button type="button" id="theme-toggle"> with an aria-pressed state and a visually hidden label joins the <header> after the <nav>, styled with the existing --text-color and --color-gray-20 border so it matches the .home-link. The handler cycles between light, dark and system, writes or removes localStorage.theme, and updates the aria-pressed and label text; the color-scheme property is set alongside data-theme so form controls and scrollbars follow.
The proof is a built site and a look at it. The agent runs npm ci and npm run build on the Node 22 from .nvmrc, checks that _site/index.html carries the inline head script and the button and that the toggle code landed in the dist bundle file, then serves _site and opens it in the sandbox browser: it captures the home page and one post in each theme, confirms the choice survives a reload and a navigation to /blog/, clears storage to confirm the system scheme returns, and tabs to the button to confirm it is reachable and announced. The four screenshots are attached to the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a dark mode toggle to this Eleventy site. Read eleventy.config.js, _includes/layouts/base.njk, _includes/layouts/post.njk, _includes/layouts/home.njk, css/index.css and css/message-box.css first, and note how addBundle lifts every <style> and <script> into per-page bundles unless marked eleventy:ignore. Move the prefers-color-scheme overrides into a data-theme attribute on html while keeping the system scheme as the default for readers who have not chosen, add an inline head script marked eleventy:ignore that applies the saved choice from localStorage before first paint, add an accessible toggle button to the header that cycles light, dark and system, and set color-scheme alongside data-theme. Run npm ci and npm run build, check the built HTML and bundle, serve _site, and in the browser screenshot the home page and one post in both themes, confirm the choice survives reload and navigation, and confirm the button is keyboard reachable. Open a pull request with the screenshots.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- 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.
- 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.
- 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
What comes back is a pull request on its own branch touching _includes/layouts/base.njk, css/index.css and css/message-box.css, with no new dependency and no change to eleventy.config.js. The CSS diff is a move rather than a rewrite: the same colour values now sit under [data-theme="dark"] and a narrowed media query, so a reader who never touches the button sees exactly what they saw before.
The description shows the four screenshots, the exact head script with a note on why it carries eleventy:ignore, and the build output listing the pages written. The transcript at GET /o/{org}/sessions/{id}/messages holds every build command and each browser step, so a reviewer can see the reload and navigation checks rather than take them on trust.
Before merging, a reviewer opens the preview, presses the button through its three states and reloads, and reads the button markup for the label and aria-pressed handling. The one judgment call left to them is the code theme: prism-okaidia.css is dark in both schemes, and the description offers a follow-up to swap in a light Prism theme under [data-theme="light"] if the team wants code blocks to change too.
Run it on every terminal hand-off
A developer who has been asked for a theme switch starts this from the terminal with this body and the site's repository in resources, then goes back to writing. The run reads the real bundle setup and the real CSS, so the head script lands where this site needs it rather than where a generic snippet would put it.
Send a request_id, a UUID, with the body so a retried start returns the run it already began. When the turn ends, GET /o/{org}/sessions/{id} names the pull request, and a follow-up to the same session can ask for the light Prism theme or a different icon on the button.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A theme toggle is a small feature with two traps that only show in a browser: a flash of the wrong palette on load, and a choice that is lost on the next page. On an Eleventy site that bundles scripts to the end of the body, the first trap is the default outcome. The agent reads the bundle configuration, places the script where it must go, and then loads the built site in a real browser to show both traps avoided.
The screenshots and the reload check are the evidence a reviewer wants and rarely gets in a pull request for CSS. Running it on Rush gives the job its own sandbox with the site's Node version, keeps every command and browser step in the transcript, and leaves a pull request a reviewer can accept from the description alone.
Frequently asked questions
Why does the head script need eleventy:ignore?
Because eleventy.config.js sets bundleHtmlContentFromSelector: "script" on the js bundle, every plain <script> in a template is moved into a bundle file loaded at the end of <body>. A theme script that runs there paints the light palette first and switches after. Marking it eleventy:ignore keeps it inline in <head> so it runs before the first paint.
Will readers who never press the button see anything change?
No. The media query is kept, narrowed to :root:not([data-theme="light"]), so a reader with no saved choice still follows their system scheme with the same colour values as before. The attribute only takes over once someone picks light or dark, and choosing system removes it again.
Does it add a dependency or a framework for the toggle?
No. The handler is a few lines of plain JavaScript that sets data-theme and color-scheme on html and writes localStorage.theme. It goes through the existing js bundle, so there is no new file to serve and no change to package.json.
What about the code blocks, which are dark in both themes today?
They stay as they are. post.njk inlines prism-okaidia.css, a dark theme, for every post regardless of scheme. The pull request leaves that alone and names it as a follow-up: a second Prism theme scoped to [data-theme="light"] is a one-file change a follow-up message to the same session can make.
More Eleventy jobs
The same job on other stacks
- Add Dark Mode to a Gatsby Blog (Gatsby)
- Add Dark Mode to a Jekyll Site (Jekyll)
- Add a Dark Mode Toggle to a Leptos App (Leptos)