Lumos Astro, officially named Lumos for Astro, is a component and styling framework for Astro websites. It supplies reusable sections and shared design tokens for typography, spacing and colour. A project still needs an agreed content-editing workflow, hosting and maintenance. Official Lumos repository.
Astro gives a marketing website control over its code, content sources and hosting. It renders HTML by default and lets developers add browser JavaScript to the parts that need interaction. That makes it a useful option for content-rich sites with custom requirements. Astro’s design principles.
Lumos adds a shared design system: reusable sections, consistent spacing and typography, and responsive layout rules. Claude Code or Codex can work within that structure, using the existing components as examples. The editing workflow and the person maintaining the code still need to be agreed before a team commits to the stack.
Astro, Webflow and WordPress compared
This comparison covers an Astro site built with Lumos, a standard Webflow site, and a conventional WordPress site. Headless and custom hosting setups can combine parts of these approaches. The table covers what each approach provides and what the team needs to set up.
| Consideration | Astro + Lumos | Webflow | WordPress |
|---|---|---|---|
| Page loading | Static HTML and zero browser JavaScript by default. Interactive features add scripts. How Astro loads pages | Managed CDN delivery. Images, interactions and added scripts affect loading. Webflow hosting | Caching can serve prebuilt HTML. Hosting, themes and plugins affect the result. WordPress performance |
| AI and MCP | Agents edit project files. Give them the Lumos guide, component examples and relevant skills. Astro Docs MCP | MCP connects agents to supported site elements, components and CMS operations. Webflow MCP | Agents can edit custom code. The official adapter connects supported WordPress operations to MCP. WordPress MCP adapter |
| Design flexibility | Control over code, content sources and interactive components. Lumos supplies shared patterns. Lumos component guide | Visual layout tools, reusable components and custom code. Webflow code components | Custom themes and plugins, with reusable blocks and patterns. WordPress patterns |
| Marketing edits | Choose a CMS and show the team how to publish and assemble pages. Astro CMS options | CMS and visual editing are part of the platform. Plan and permissions determine access. Webflow CMS | A built-in content editor. Theme and plugin choices shape the editing experience. WordPress editor |
| Hosting | Choose a static host or compatible server runtime. Set up deployment for the project. Astro hosting options | Managed hosting is the usual route. Webflow Enterprise custom hosting is also available. | Choose a managed host or run the server stack. Agree who maintains it. WordPress hosting |
| Maintenance | Keep dependencies, shared components and integrations current. Our maintenance routine | Webflow maintains its platform. Your team owns content, integrations and custom code. | Keep core, themes and plugins current, with backups and compatibility checks. WordPress updates |
Sources linked in the table were checked on 14 September 2026. Loading depends on the finished page, including its images and added scripts. Our article recorded 97/100 for desktop performance and a 1.3-second Largest Contentful Paint on 9 September. The measurement details describe that single-page lab test.
The Lumos Astro design system
Lumos for Astro is a framework by Timothy Ricks with reusable components and a design system for Astro websites. Shared tokens define the site’s typography, spacing and themes. Components use those values consistently. Lumos repository.
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 the framework gives the team
| Lumos provides | Practical benefit |
|---|---|
| Reusable components | An approved button or section can be used across pages. A shared fix reaches its existing instances. |
| Spacing and typography tokens | Brand values have a defined home. Editors and developers can follow the same scale. |
| Responsive patterns | Fluid values and layout rules provide a consistent starting point across screen sizes. Test real content at the breakpoints. |
| Themes and variants | A section can use an agreed colour theme or layout variant while retaining the shared component structure. |
| Instructions for future changes | A maintainer or coding agent can inspect the actual component API and follow the same conventions. |
These benefits depend on keeping pages connected to the shared components. Copying a section and rewriting its styles creates a separate maintenance job. A framework also needs checks with long copy, missing images and keyboard interaction. Its starter cannot guarantee the quality of every later customisation. Lumos build instructions.
How Lumos Astro styles cascade
CSS becomes harder to maintain when each new section adds its own overrides. A developer needs to understand which rules take priority before changing a shared component.
Lumos splits its styles into 4 layers in a fixed order: base, patterns, components, utilities. For normal declarations within those layers, a later layer takes priority over an earlier one before selector specificity is considered. Unlayered styles and important declarations have different precedence rules, so a project still needs a review of its custom CSS. The cascade guide.
A declared order for normal styles within the framework
- 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.
How to start a Lumos for Astro project
Start a Lumos for Astro project with npm create lumos@latest my-site, then run cd my-site and npm run dev. The starter provides the project setup, design tokens and component library. Its current setup requires Node 22.12 or newer. Lumos installation instructions.
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!
Building Lumos Astro pages with AI
Give the agent the project’s rules and examples before asking it to build a page. It needs to know which section component to use, where spacing comes from and how a finished change reaches the website.
For someone coming from Webflow, think of this as giving a new builder access to the style guide, component library and publishing instructions. In an Astro project, those instructions live in files alongside the website.
The context files to provide
| File or reference | What it tells the agent |
|---|---|
| Project instructions | CLAUDE.md for Claude Code and AGENTS.md for Codex. Name the site, key folders, build commands and release rules. Point both files to the same shared project guide. Claude project instructions; Codex project instructions. |
| Lumos build guide | LUMOS.md explains the framework conventions. Include the actual section, grid, typography and button components from the installed project. Read the Lumos guide. |
| An approved section | A real section with its content, layout and mobile behaviour. Tell the agent which existing component and spacing options to reuse. |
| Skills for repeatable jobs | A skill is a written procedure, usually a SKILL.md file. Provide the relevant build, deployment or maintenance skill for the current job. Claude skills; Codex skills. |
| Hosting and editing notes | Where content is edited, how previews work, which Cloudflare project hosts the site and how to restore a release. Keep passwords and tokens in the hosting or agent secret settings. |
Three skills to prepare
These are suggested project skills. Write each one around the actual components, commands and hosting account used by the site.
Build a section, publish a preview, maintain the site
- Build a Lumos sectionRead the guide and a matching example. Reuse the section wrapper, tokens and buttons. Check short and long copy on desktop and mobile.
- Deploy to CloudflareConfirm the project and preview branch. Run the build, check the preview and forms, then follow the site's agreed production release steps.
- Maintain the websiteRead the change notes. Find every page using the component. Check the change in a preview and record how to restore the previous release.
Start with one complete section. For example: “Read the Lumos guide and our section-building skill. Add a testimonial section using the existing Section and typography components. Reuse our spacing options and show the desktop and mobile preview.” Once that example is approved, the next page has a working reference.
Maintaining an Astro website with AI
Suppose a marketing team needs to change the main call-to-action button. Give the agent the component guide and maintenance skill, then ask it to find the shared button and the pages that use it.
- Describe the change. “Change the primary button label to Book a demo. Keep the existing style and destination.”
- Check a preview. Look at the homepage and a longer landing page. Check that the label fits on a phone and the button opens the right page.
- Publish and check it live. Follow the saved deployment instructions and confirm the change reached the website.
- Leave a short note. Record what changed and how to restore the previous version so another person can pick it up later.
Content edits can happen in the chosen CMS. Changes to code, packages or integrations need someone who can assess the result. Agree who handles those jobs before launch. Our AI setup and Cloudflare checklist gives the team a practical starting list.
What does an Astro site actually deliver?
Our agency site uses Astro’s static rendering to produce HTML at build time. Interactive features add their own JavaScript. The site predates the current Lumos starter and has its own styling layer. These measurements describe that implementation on 9 September 2026; they measure page loading, and give no estimate of development time.
This article's page on legencymedia.com, desktop Lighthouse, 9 September 2026
The 74 kB script transfer includes the smooth-scroll and table-of-contents behaviour we chose to add. This was a desktop lab test. A mobile performance claim needs its own measurement under stated conditions.
Static pages can be served from a managed hosting platform. The project still needs someone responsible for its dependencies, CMS, forms and other services. Include those accounts and their costs in the proposal.
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 Astro web development page covers what a build includes and when we recommend it. 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.
Which websites suit Astro
Our recommendation starts with the site’s operating needs. Astro supports both content sites and dynamic routes; the surrounding services determine what the finished system can do. Astro rendering options, ecommerce options.
| Website type | Where Astro fits | Decision to settle first |
|---|---|---|
| Small business or brochure site | A mostly static site with clear content and modest interaction. Astro for content sites | Who changes opening hours, adds pages and receives form enquiries? Compare the support cost with a managed visual builder. |
| B2B or enterprise marketing site | Custom content models, substantial publishing and integrations with a product or marketing stack. CMS options | Specify editor roles, approval stages, localisation, uptime support and ownership across every connected service. |
| Ecommerce storefront | A custom frontend connected to a commerce platform or payment service. Commerce options | Who owns inventory, pricing, checkout, tax, shipping, refunds and order support? Include the cost of maintaining that connection. |
| Portal or highly interactive application | Astro can render dynamic routes and add interactive components. Dynamic pages | Define authentication, permissions, shared application state and data freshness before selecting the architecture. |
For a straightforward shop, compare a complete commerce platform before commissioning a custom storefront. An enterprise marketing site may be mostly static and still need complex governance. Page count and traffic alone do not decide the stack.
Where an Astro site is hosted
This website runs on Cloudflare Pages. Astro also documents deployment to providers including Netlify and Vercel. Static pages can be distributed as built files; pages that generate personalised content on request need a compatible runtime and adapter. Astro deployment guide.
Hosting is one line in the operating cost. Include the CMS, forms, search, image services and any server functions used by the site. Agree account ownership, usage limits, preview access, backups and rollback. A free hosting tier does not establish the total cost of running the website.
What Astro and Webflow cost to run
Prices checked 14 September 2026. Figures below are in USD before tax. Webflow Basic and Premium show the monthly equivalent when billed annually. Astro costs depend on the host, CMS and services you choose.
| Cost to budget | Astro on Cloudflare | Webflow |
|---|---|---|
| Static website hosting | $0 on the Pages Free plan for an eligible static site. Static asset requests are free; build and file limits still apply. Pages pricing; plan limits. | Basic: $15/month, billed yearly ($180/year). Custom domain hosting, no CMS. Webflow plans. |
| Blog and content editing | Markdown files have no separate CMS subscription. A visual CMS may charge for seats, usage or features; allow for connecting it. CMS options. | Premium starts at $25/month, billed yearly ($300/year). Includes the CMS; bandwidth options change pricing. Premium pricing. |
| Forms and server features | Functions have a free usage allowance. Budget separately for form delivery. Workers Paid has a $5/month account minimum, plus usage above allowances. Choose the paid plan when its allowances or features are needed. Workers pricing. | Basic and Premium list unlimited form submissions. Apps, CRM connections and extra services can add charges. Included features. |
| Team access and governance | CMS seats, hosting access, previews, approvals and support depend on the services chosen. Price the required setup together. | Check Workspace and seat needs. Team: $2,500/month with an annual contract; Enterprise is quoted. These include broader platform capabilities. Team and Enterprise. |
| Domain and optional services | Domain renewal, email, search, localisation, analytics and media services are separate where used. | Domain renewal and business email are separate. Localisation, analytics, optimisation and apps may add charges. |
| AI building tools | Include the Claude Code or Codex plan and any extra usage. These are development costs alongside hosting. | External coding agents or paid tools may add costs alongside the Webflow plan. |
| Build and maintenance time | Allow for setup, CMS integration, dependency updates, forms, previews and recovery. Agree who handles them. | Allow for design, content, integrations and custom-code support. Webflow maintains the hosted platform. |
| Ecommerce | A commerce backend, checkout and payment processing have their own charges. Astro commerce options. | Compare Ecommerce plans and payment fees separately. Basic and Premium figures above describe marketing sites. Ecommerce pricing. |
A static brochure site can have a $0 Cloudflare hosting bill, with domain renewal and maintenance still to cover. A blog with a visual CMS adds the selected CMS and integration costs. Compare the complete annual setup with the Webflow plan that meets the same editing and support needs. The Team plan’s governance and support scope also needs an equivalent specification before comparing totals.
When a marketing team builds it themselves
A team using AI can create an initial page and still have several decisions open. Someone needs to turn the design into reusable components, define the content fields, set up publishing and verify that enquiries arrive. Adding a generated contact form to a page does not establish its destination or spam handling.
Try a complete rehearsal before committing: publish an article, assemble a campaign page, change a shared component and restore the previous release. Use the accounts and permissions the team will have after launch. If those tasks depend on one person’s chat history, put the missing instructions and ownership into the project.
A marketing team with technical support can run that process itself. A team wanting to own layout and publishing through a visual interface should compare the demonstrated CMS workflow with Webflow or WordPress. Our Astro planning checklist includes the hosting and handover decisions to work through.
What should you know before choosing Lumos?
Lumos for Astro is still in beta. The local reference reviewed on 9 September 2026 was version 0.0.3, 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.
The starter records the commit the site came from, and its upgrade instructions describe merging upstream changes with the project’s customisations. We record the starting version in every project, review the diff and verify the resulting pages 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.
Frequently asked questions
What is Lumos Astro?
Lumos Astro is a common name for Lumos for Astro, a component and styling framework for Astro websites. It provides reusable sections and shared design tokens. The project team chooses the content-editing workflow, hosting and maintenance arrangements.
