Table of contentsShowHide
Astro Rocket is a free, open-source Astro theme, listed in the official Astro themes directory, with 85 stars and 42 forks from developers around the world. This post is the one I wish I’d read before I built it: what a theme actually is, the architecture decisions that matter, and the parts nobody warns you about — with the honest lessons included.
A theme is not a website
The most important thing I learned came first, and it changed everything after it.
When you build a website, you’re building for one owner: yourself, with your own content, your own taste, and the freedom to fix anything the moment it bothers you. When you build a theme, you’re building for every owner — people you’ll never meet, with content you can’t predict, on sites you’ll never see. The code looks similar. The discipline is completely different.
Concretely, that discipline means three rules I now treat as law:
- Every change must work everywhere. In all twelve colour themes, in light and dark mode, on every page type. That’s twenty-four visual combinations per change, before you even reach responsive breakpoints.
- New features ship opt-in and off by default. Someone built their business site on your theme eight months ago. Your next release must never change what their visitors see. If a feature is on by default, it’s a breaking change wearing a disguise.
- If it isn’t documented, it doesn’t exist. Users can’t read your mind, and “look at the source” is not documentation — it’s homework.
Start from a real website, not a blank canvas
Astro Rocket didn’t start as a theme. It started as my own website — which itself started from Velocity, a well-engineered open-source boilerplate. I built for three months, and somewhere along the way realised the thing had outgrown one website. So I made a version with demo content and released it.
I’d now recommend that order to anyone: build a real site first, extract the theme second. A theme designed in the abstract solves imaginary problems. A theme extracted from a real site has already survived real content, real pages, and real decisions — its patterns exist because something needed them. The demo site isn’t a brochure; it’s the proof.
The architecture that survives strangers
The technical choices that mattered most, in the order I’d make them again:
A component library with one design language. Astro Rocket is built around 57 components that share the same spacing rhythm, the same colour tokens, and the same interaction patterns — so whatever a user assembles from them looks intentional. This is the heart of the theme. Everything else is arranged around it.
Design tokens, not hard-coded values. Every colour is a token, every spacing step is a variable. That’s what makes twelve colour themes possible at all: the palette switches, and every component follows because none of them ever knew a specific colour to begin with.
Typed content collections. Posts, projects, and pages are validated by a Zod schema at build time. On a theme this matters double: your users will feed it content you never imagined, and a build error with a clear message is a kindness — silent breakage on their live site is not.
Config over code edits. Everything a user should be able to change — site name, navigation, features on or off — lives in config files, not in component internals. Every option a user can set without touching a component is an update they can pull without a merge conflict.
Colour themes and dark mode: the combinatorial tax
Here’s the part nobody warned me about. One design, checked in light and dark mode, is two reviews. Twelve colour themes make it twenty-four. A component that looks perfect in blue light mode can quietly lose all contrast in amber dark mode — and a theme user will find that combination, because to them it isn’t an edge case; it’s their website.
The practical answer is contrast-checked tokens: every colour role in every palette is verified against WCAG in both modes, once, at the token level — so individual components inherit correctness instead of each needing its own audit. Holding the theme’s perfect Lighthouse score across all of it works the same way: it’s dozens of small decisions made once, at the foundation, instead of dozens of repairs made forever.
Documentation is half the product
I underestimated this at the start, and I suspect everyone does.
A theme’s real product is the website someone else builds on it — which means every question they can’t answer is a wall between them and that website. So the documentation grew into its own discipline: written guides for the major systems on the theme’s blog, a README that explains rather than lists, and — the part I’d stress most — a demo that doubles as documentation. Every feature of Astro Rocket is visibly used somewhere on the demo site. When a user wonders how something works, they can look at where it works.
The payoff is quiet but real: every question the docs answer is an issue nobody has to open.
Getting into the official directory
Being listed in the official Astro themes directory changed the theme’s reach — it’s where developers actually look. The submission itself happens on astro.build, but the checklist worth completing before you submit is the real work: a live demo that works, a README that explains setup honestly, an open-source licence, and a repository someone can clone and run without asking you anything.
None of that is bureaucracy. It’s exactly the bar your future users will hold you to anyway — the directory just asks first.
Maintaining in the open
Releasing the theme turned out to be the halfway point, not the finish line. What happens after is the part that made me a theme developer rather than someone who once published a repository.
Users open issues. Some report bugs; the best ones request enhancements you didn’t see coming. The theme’s built-in internationalisation became one of its most complete features through a series of issues from one dedicated user — request by request, discussed in the open, shipped within days. My work built the theme; its users are making it better than I could alone.
And once, the community stopped me from a mistake. A user proposed a full design-consistency system, and I implemented it as the new default — it was thorough, well-argued work. Other users pushed back: the theme had lost the varied feel they’d chosen it for. The default went back, and the new design lives on as an official variant on its own branch. The lesson stayed with me: a theme’s default design belongs to the people who chose it. Change it under their feet, and no amount of consistency pays for what it costs.
What I’d do differently
Honesty section, because every “how to” post should have one:
- I’d design for internationalisation from day one. Retrofitting i18n into a finished theme meant moving every string on every page into locale dictionaries — it works beautifully now, but building it in from the start would have cost a fraction of the effort.
- I’d start the changelog with the first release, not when it became necessary. Users updating a theme need to know exactly what changed and whether anything needs their attention. A disciplined changelog is cheap on day one and expensive to reconstruct later.
- I’d trust the demo-first instinct sooner. The features that came out best were extracted from something real. The few I designed in the abstract needed the most rework.
The bottom line
Building an Astro theme is building a website, plus a promise: that it works everywhere, breaks nothing, and explains itself. The website part took me three months. Learning to keep the promise is the actual craft — and it’s the part that keeps going, release after release.
If you’re thinking about building one, the route that worked for me: start from a solid open-source base, build a real website on it, and extract the theme from what survives — with every colour a token, documentation written as you go, and the result put where developers look. And if you’d rather begin the way I did — from a shipped, working theme — Astro Rocket is free, MIT-licensed, and ready to take apart.