# Add Dark Mode to a Lit Component

Yes. An agent gives your Lit component a dark theme with CSS custom properties, a prefers-color-scheme default, a theme attribute and browser tests, and opens a PR.

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

## What the agent does

In a component like lit/lit-element-starter-ts, the agent reads `src/my-element.ts`: `MyElement` extends `LitElement` with `static override styles = css` holding one `:host` rule, `display: block`, a `solid 1px gray` border, `16px` of padding and an `800px` max width; a `name` property and a `count` property; a `render` that writes an `h1`, a `button` with `part="button"` and a `slot`; and a `_onClick` that increments `count` and dispatches `count-changed`. The JSDoc above the class carries `@fires`, `@slot` and `@csspart` tags, which `npm run analyze` turns into `custom-elements.json` through `cem analyze --litelement` and the Eleventy docs under `docs-src` render as the API page. `src/test/my-element_test.ts` uses `fixture` and `assert.shadowDom.equal` from `@open-wc/testing` under `@web/test-runner` with the Playwright launcher in `dev` and `prod` modes, `dev/index.html` is the manual demo page, `tsconfig.json` turns on `experimentalDecorators` and the strict `ts-lit-plugin`, and `lint` runs `lit-analyzer` and ESLint.

A reusable element should not decide the page's theme, so the agent expresses dark mode as tokens the host page can set and defaults the element supplies. The styles gain `--my-element-background`, `--my-element-color`, `--my-element-border-color`, `--my-element-button-background` and `--my-element-button-color`, used through `var()` with light fallbacks in the `:host` rule, and a `@media (prefers-color-scheme: dark)` block that changes the fallbacks to dark values. `color-scheme: light dark` on `:host` lets the native button and any scrollbar follow the same choice. For pages that switch themes themselves, a `theme` property declared with `@property({ reflect: true })` and typed `'light' | 'dark' | 'auto'` with `'auto'` as the default reflects to an attribute, and `:host([theme="dark"])` and `:host([theme="light"])` rules override the media query either way, so `<my-element theme="dark">` is dark on a light page. Each token gets a `@cssprop` line in the JSDoc and `theme` an `@attr` line, so the manifest and the docs list them.

The tests are where the browser matters. `@web/test-runner-commands`, which works with the Playwright launcher the config already uses, provides `emulateMedia`, so a test sets `colorScheme: 'dark'`, mounts the element with `fixture`, and reads `getComputedStyle(el).backgroundColor` and the border colour against the dark values; the next test keeps dark media and mounts `theme="light"` to see the override win; a third sets `el.theme = 'dark'` and checks the attribute reflected; and a `teardown` resets the emulation so the existing tests see light media. The `shadowDom.equal` snapshot in the existing test does not change, since the markup is the same and the theme lives in the attribute and the styles. `npm test` runs the suite in both modes, and `dev/index.html` gets a theme toggle for a person to look at it.

The agent runs `npm run lint`, where `lit-analyzer` in strict mode checks the new attribute against the declared property, `npm test` for both modes, `npm run analyze` to regenerate `custom-elements.json` and read the new `cssProperties` and `attributes` entries, and `npm run docs` to build the site and confirm the API page shows them. The pull request shows the token table with light and dark defaults, a screenshot of the demo page in each theme from the sandbox browser, and the test output.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add dark mode to the component in this Lit package. Read src/my-element.ts, src/test/my-element_test.ts, web-test-runner.config.js, dev/index.html, package.json and tsconfig.json first. Express the theme as CSS custom properties with light fallbacks, a prefers-color-scheme dark block, and color-scheme on the host, plus a reflected theme property with light, dark and auto values whose attribute selectors override the media query. Document each custom property and the attribute in the JSDoc so the custom elements manifest lists them. Add browser tests that emulate the dark colour scheme with web-test-runner commands, check the computed colours, check the override and the reflected attribute, and reset the emulation afterwards. Add a theme toggle to the demo page. Run lint, the tests in both modes, the manifest analysis and the docs build, and open a pull request with the output and screenshots of both themes.",
  "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

The pull request changes `src/my-element.ts`, `src/test/my-element_test.ts`, `dev/index.html`, `package.json` and `package-lock.json`. Its description holds the table of custom properties with their light and dark defaults, two screenshots of the demo page, the `custom-elements.json` entries the analysis produced, and the `lint` and `test` output for the `dev` and `prod` runs.

Where the repository has a test workflow it runs the Playwright suite on the pull request, including the three new cases; where it has none, the sandbox run in the record is the evidence. The existing `shadowDom.equal` test passes unchanged, which shows the markup did not move.

Before merging, a reviewer picks the actual dark values, decides whether `auto` should be the default or whether the host page should always set `theme`, and whether the button's `part` should expose a second part for the hover state. The properties, the event and the slot are unchanged.

## Run it on every design request in the backlog

A team that tracks design work in Linear adds an automation on the Project with a `linear` trigger on issues labelled `design` and this prompt. When an issue such as "the widget is blinding on our dark dashboard" gets the label, a run starts in the repository, does the work above against that component's own styles and tests, and opens a pull request that links the issue. The trigger adds the issue after the prompt, so one prompt serves every such issue.

The same body sent to `POST /o/{org}/sessions`, with a `request_id` that is a UUID v5 of the issue's identifier, does the same for one issue by hand. The key's `webhook_url` reports each run the key starts with the pull request in `result`; a run an automation starts appears in the Project's run list and has its own `max_runs_per_hour` cap.

## Why run it on Rush?

Dark mode in a shared component is a design decision with a testing problem attached: the right shape is tokens plus a media query plus an explicit override, and the proof needs a real browser whose colour scheme the test can set. The agent writes the three layers, documents them where the manifest will find them, and runs the Playwright suite with emulated media in its own sandbox.

The computed-colour tests, the regenerated manifest and the screenshots of both themes stay with the run and are quoted in the pull request. A team with several component packages gets the same tokens and the same tests per repository, each fitted to that component's styles.

## Frequently asked questions

### Why custom properties instead of a dark stylesheet?

The element's styles live in its shadow root, where a page stylesheet cannot reach, but custom properties inherit through the shadow boundary. Tokens let a host page set `--my-element-background` once for its own theme, while the element's fallbacks and media query give a sensible result on a page that sets nothing.

### What does the theme attribute do that the media query does not?

The media query follows the operating system. A page with its own theme switch needs to override that, so `theme="dark"` and `theme="light"` win over the media query through attribute selectors on the host, and `auto`, the default, defers to it. The property reflects so the attribute and the property stay in step.

### How can a test check the dark colours?

`@web/test-runner-commands` exposes `emulateMedia`, which tells the Playwright browser to report a dark colour scheme for the page. The test mounts the element, reads `getComputedStyle`, and compares the background and border colours to the dark values; a `teardown` resets the emulation so the existing tests still see light.

### Do the docs pick up the new properties?

Yes. `@cssprop` and `@attr` tags in the class JSDoc are read by `cem analyze --litelement` into `custom-elements.json`, and the Eleventy docs render that file as the API page. The agent runs the analysis and the docs build and shows the generated entries in the pull request.

## More Lit jobs

- [Add Dependabot to a Lit Component Project](https://getrush.ai/run/add-dependabot/lit/)
- [Add a Deploy Workflow for a Lit Component's Docs Site](https://getrush.ai/run/add-deploy-workflow/lit/)
- [Add GitHub Actions CI to a Lit Web Component Project](https://getrush.ai/run/add-github-actions-ci/lit/)

## The same job on other stacks

- [Add Dark Mode to a Pelican Blog](https://getrush.ai/run/add-dark-mode/pelican/)
- [Add a Dark Mode Toggle to a Phoenix LiveView App](https://getrush.ai/run/add-dark-mode/phoenix-liveview/)
- [Add Dark Mode to a React App](https://getrush.ai/run/add-dark-mode/react/)

## 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/)
