All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading