A custom website involves plenty of decisions before you’ve built anything specific to the business. You need rules for buttons, spacing, headings and colour themes. Then you start another project and make a lot of the same decisions again.
We’ve been using Lumos in Webflow for a while, and we’re now following Lumos for Astro too. Having a familiar set of rules gives us a better place to begin. The useful work is deciding how those rules should serve the website we’re building, and this piece is about where that line sits.
What is Lumos for Astro?
Lumos for Astro is a framework by Timothy Ricks with reusable components and a design system for Astro websites. Its own description is a good one: a set of design tokens, a predictable cascade, a library of utility classes and a set of components that already know how to be accessible. Lumos documentation.
If you’ve worked with Lumos in Webflow, the thinking will feel familiar. A component should pick up the colours of the section it’s in. Spacing should follow an agreed scale. Changing the brand’s heading style should have a predictable effect across pages.
I like that because the alternative can become a fairly tedious job: opening individual components to work out why each one looks slightly different. A consistent starting point makes the next change easier to understand.
What Lumos settles, and what still has to be decided for your business
Lumos decides
- Type scale
- Space scale
- Colour themes
- Cascade order
- Section and grid components
- Buttons, tabs, accordions, forms
- Focus and keyboard behaviour
- Fluid sizing from 320px to 1440px
Your project decides
- Brand values in the tokens
- Page structure
- Content model
- Who edits, and how
- Forms and CRM
- Hosting and backups
- Tracking
- Custom sections
What does a predictable cascade mean in practice?
This is the part I’d point a developer at first. In ordinary CSS, when two rules apply to the same element, the more specific selector wins. That’s why stylesheets rot. To override something you write a longer selector, then someone overrides that with a longer one, and after a year the only thing that works is a rule nobody wants to touch.
Lumos splits its styles into four layers in a fixed order: base, patterns, components, utilities. A later layer beats an earlier one whatever the selectors say. A one-class utility beats a component’s twelve-selector rule every time, without a fight. The cascade guide.
A later layer always wins, so nobody needs to know anyone else's selectors
- BaseDesign tokens, colour themes, the reset and text styles. What a heading looks like anywhere on the site.
- PatternsThe shapes that repeat: a container, a flex row, a grid. Shared between components.
- ComponentsEach component styles itself and may override any pattern it uses.
- UtilitiesThe last word. A one-off adjustment that belongs to this instance and nothing else.
The tokens follow the same idea of one place to change. Most of them are fluid: a space value might be 20px at a 320px viewport and 24px at 1440px, and it slides between the two. There’s no tablet breakpoint where the padding suddenly jumps, which also means one less set of numbers to design and maintain. The tokens guide.
Does a custom Astro build have to start from scratch?
You can start with an established framework and build the company’s own design on top of it. The current starter is one command, npm create lumos@latest, and it gives you the initial setup, the token file and the component library. Lumos installation guide.
There’s still plenty to decide. A product page might need a comparison section, a pricing calculator or a connection to the sales team’s CRM. Those requirements come from the business. The framework gives us somewhere sensible to put them.
That’s how we’re approaching it at Legency. We want a reusable foundation for new Astro projects, with the design and content worked through for each client. Rebuilding the same button from a blank file doesn’t add much to that process!
What does an Astro site actually deliver?
Astro renders pages to plain HTML at build time and only sends JavaScript for the parts of a page that need it. That’s the whole pitch, and it’s easy to state and harder to prove, so here are our own numbers. Our agency site runs on Astro. It’s an older build than the Lumos starter, with its own styling layer, so treat these as what Astro delivers rather than what Lumos adds.
This article's page on legencymedia.com, desktop Lighthouse, 9 September 2026
The numbers I’d draw your attention to are the JavaScript and the request count. A page like this one ships about 74 kB of script, most of it the smooth-scroll and table-of-contents behaviour we chose to add. A comparable WordPress page with a page builder and a handful of plugins commonly ships several hundred kilobytes before any content loads. The difference is what a visitor on a phone feels as the page appearing straight away.
The hosting side is also worth saying plainly. A static Astro site is a folder of files, so it sits on Cloudflare Pages, Netlify or similar with no server to patch. Our own hosting bill for legencymedia.com is zero. That’s a real line in a proposal, and it changes what “ongoing costs” means for a marketing team.
Who will update the website?
This is one of the first conversations I’d have before recommending an Astro build. Who is adding the next article? Who needs to create a campaign page? How much of that should they be able to do themselves?
Astro can connect to a CMS, which gives the team an interface for managing content. The CMS and the way we connect it determine what editing, previews and approvals actually look like. Astro’s CMS guide.
How a new article reaches the live site under each editing model
Files and version control
- Write a Markdown fileTitle, date, cover and body in one text file.
- Open a pull requestA preview build appears on its own URL for review.
- Merge and deployThe site rebuilds and goes live. Every change is recorded and reversible.
A connected CMS
- Write in the CMSAn editor fills in fields and picks sections from an approved set.
- Preview and approveA draft link goes to whoever signs it off.
- PublishThe CMS triggers a rebuild. No developer involved.
A blog editor and someone assembling landing pages may need quite different controls. I’d want to show both people their usual tasks before we agree the build. Finding out at handover that the marketing team can’t add a section would be a fairly avoidable problem.
Our Webflow Enterprise work starts with the same conversation. The people running the site need to be comfortable using it after launch, and for a team publishing several times a week with no developer nearby, Webflow is still often the right answer. Astro earns its place when the site is content-heavy, performance matters commercially, and someone technical will be around to keep it running.
What should you know before choosing Lumos?
Lumos for Astro is still in beta. The package is at version 0.0.3 as I write this, and the repository is direct about what that means: every 0.x release is allowed to break things, and version 1.0 is where the API gets committed to. Component props will be renamed and classes will change before it settles. Lumos repository.
That’s less alarming than it sounds, because the starter stamps the commit your site came from, and an upgrade tool three-way merges each release into your own changes and pixel-diffs every page. An upgrade becomes a reviewed diff rather than a rewrite. We record the starting version in every project and review changes before adopting a newer release.
It also won’t decide who maintains your dependencies, where your forms send enquiries or how you recover a failed release. Those belong in the project scope, alongside the design work, and they’re the items that most often turn up missing from an Astro proposal.
If you’re considering an Astro build, our twelve questions to ask before an agency builds your site in Astro cover the ground we’d work through together. Bring it to the scoping conversation and get the editing workflow demonstrated while there’s still room to change it.
