Starlight Visual Customizer
A free visual theme editor for Starlight. Restyle colors,
fonts, layout and components on real Starlight pages, then export one CSS file.
Starlight Visual Customizer is an independent, open-source project by Prisant Labs, released
under the MIT license. It is not affiliated with or endorsed by the Astro team.
Starlight's built-in color theme editor sets an accent color and a gray. This editor covers
typography, layout and component styles too. Every change appears at once on real Starlight
pages, in light mode and dark mode.
What you can do
- Start from a preset. Nine presets range from Starlight's own default to Editorial Serif and
High Contrast Mono. Every value stays editable after you pick one.
- Change the whole look, not just the palette. Colors, fonts, the type scale, the content
width, the header, the sidebar, the table of contents, callouts, cards, tables, tabs, code
blocks and the footer each have their own controls.
- See your theme on real pages. The preview is an actual Starlight build in a frame, not a
mockup. Switch between a style guide, a long document, a landing page and the 404 page.
- Check light and dark together. Split view shows both modes side by side. The contrast check
above the preview reports whether text color pairs meet WCAG AA contrast in both modes.
- Find the control for any element. Turn on Inspect, then click an element on the page to
open the controls that style it.
- Preview at real sizes. Device widths run from a 390-pixel phone to a 2560-pixel ultra-wide
screen.
- Undo anything, and share the result. Every change is one undo step. A share link carries
the whole theme and the page you were viewing in its URL. Opening one never silently replaces
a theme you saved: the studio asks first.
How export works
Export gives you two ways to get a theme onto your own site, each one click. The theme uses
Starlight's own customCss option, so there is no plugin to install.
- Copy for your coding agent copies one message with the setup steps and the whole stylesheet,
to paste into Claude Code, Codex, Cursor or similar.
- Download the files (.zip) downloads
theme.css and APPLY-THEME.md, numbered setup steps
you can follow yourself, in one folder.
The studio also exports its own settings, so you can import a theme later and keep editing, and a
PNG screenshot of the preview.
The steps inside APPLY-THEME.md (or the pasted message) are generated for each theme, and they
are the same every time:
- Add the theme's CSS to
src/styles/theme.css in your project.
- In
astro.config.mjs, add that file as the last entry of Starlight's customCss array.
The theme's CSS is unlayered, so the last entry wins any tie with another stylesheet.
- If you picked a non-default web font,
npm install each @fontsource-variable/<font>
package the file lists.
- Rebuild.
A round-trip test checks this promise. It applies a real export to a freshly scaffolded Starlight
site, then compares the computed styles with the studio's own live preview.
Privacy
Your theme never leaves your browser. The state, the preview and the export all run and stay on
the client, in localStorage and, if you use one, a share link. The studio makes only one kind of
network request on its own: it loads the variable web fonts you preview from cdn.jsdelivr.net
(Fontsource). THIRD-PARTY-NOTICES.md lists every dependency and its
license.
Run it locally
You need Node 22.
cd app
npm install
npm run build
npm run preview:bg # serves dist/ in the background on http://localhost:4420
Open http://localhost:4420/studio/. The studio opens on the demo site's style guide page. Pick
a preset, adjust the controls, then open Export.
docs/development.md covers the dev server, the ports and the background
servers.
Serving under a sub-path
The app builds for / by default. To serve it under a sub-path, such as a GitHub Pages project
site at https://<user>.github.io/<repo>/, set SVC_SITE_BASE before astro build and
astro preview. Every internal link goes through one base-path helper, so nothing else changes.
See "Serving under a sub-path" for the exact
commands.
Tests
| Suite | What it checks |
|---|
npm test (291 unit tests) | The CSS, APPLY-THEME.md and agent-message emitters, the manifest, state, share-link decoding, the checks on every theme that comes from outside the studio, sidebar-link safety, color math, the sidebar parser, undo and redo, and the base-path helper. No browser needed. |
npm run test:e2e (14 browser suites) | The product page, every control's visual effect and target, the studio shell, Studio sizing, share links, Inspect, hex color entry, the structure editor, PNG screenshot export and the Export dialog, against a running preview |
npm run test:roundtrip | Applies a real export to a freshly scaffolded Starlight site and compares its computed styles with the studio's live preview |
Every pull request runs the unit tests and a production build in CI. The suite-by-suite
breakdown and commands are in docs/testing.md.
Documentation
docs/ documents the project for people who want to understand, change or
maintain it. It covers what each part of the studio does, the
export format, the architecture, the
security model, and the decisions behind the
design. Coding agents start at AGENTS.md.
Built with
Astro and Starlight, with
culori for color math, vanilla-colorful
for the color picker, fflate for the zip download and
modern-screenshot for PNG export.
Contributing
Bug reports, ideas and themes are welcome. Report a bug under
Issues, and bring
questions and ideas to
Discussions. To share a
theme, post its share link in Show and tell. SUPPORT.md lists where every kind of
question goes. CONTRIBUTING.md explains how to run the app and its tests.
SECURITY.md explains how to report a vulnerability privately, and
ACCESSIBILITY.md explains how to report an accessibility barrier.
Releases
Each release is tagged, and its notes are on the
Releases page. The same
notes live in the repository under docs/releases/, one file per
release. CHANGELOG.md lists the notable changes in each release.
License
MIT. Third-party licenses and attributions are in
THIRD-PARTY-NOTICES.md.
Your exported themes are yours. The MIT license covers the studio's own source code. The
files you export (theme.css, APPLY-THEME.md, the agent message and the settings file) are
yours to use, change and publish however you like, with no attribution or license notice required.
theme.css names this tool, with a link, in its header comment, and APPLY-THEME.md and the
agent message each end with the same line; keep them or delete them.
Starlight Visual Customizer is an independent, open-source project by Prisant Labs. It is not
affiliated with or endorsed by the Astro team.
