Start hereLumos 0.0.1Updated

Project structure

What every folder in a Lumos project holds, and which files you are meant to edit.

A Lumos project is a normal Astro project. If you have seen one before, nothing here will surprise you.

The shape of it

src/
  assets/       images, icons and logos you import
  components/   the framework's components
  layouts/      page shells
  pages/        one file per URL
  styles/       base.css, patterns.css, utilities.css, global.css
  utils/        small helpers
  consts.ts     site name, description, URL, locale
  types.ts      shared prop types
public/         files served exactly as they are
astro.config.mjs

src/
  assets/       images, icons and logos you import
  components/   the framework's components
  layouts/      page shells
  pages/        one file per URL
  styles/       base.css, patterns.css, utilities.css, global.css
  utils/        small helpers
  consts.ts     site name, description, URL, locale
  types.ts      shared prop types
public/         files served exactly as they are
astro.config.mjs

Pages are URLs

Every file in src/pages becomes a page on the site, and its path becomes the URL. src/pages/about.astro is /about. src/pages/work/index.astro is /work. There is no separate router to configure and no page settings panel: the folder structure is the site map.

What an .astro file looks like

Two parts, separated by three dashes. Above the dashes is setup: imports and any values you want to work out first. Below is the markup.

src/pages/about.astro

---
import BaseLayout from "@/layouts/BaseLayout.astro";
import Section from "@/components/Section.astro";
import Heading from "@/components/Heading.astro";
import Paragraph from "@/components/Paragraph.astro";
---

<BaseLayout title="About">
  <Section>
    <Heading tag="h1">About us</Heading>
    <Paragraph>We make things.</Paragraph>
  </Section>
</BaseLayout>

---
import BaseLayout from "@/layouts/BaseLayout.astro";
import Section from "@/components/Section.astro";
import Heading from "@/components/Heading.astro";
import Paragraph from "@/components/Paragraph.astro";
---

<BaseLayout title="About">
  <Section>
    <Heading tag="h1">About us</Heading>
    <Paragraph>We make things.</Paragraph>
  </Section>
</BaseLayout>

The @/ at the start of an import means from the src folder, so you never have to count how many ../ it takes to get somewhere.

Which files you edit

Folder	Yours to edit?	What it holds
`src/pages`	Always	Your pages. This is where most of the work happens.
`src/consts.ts`	Always	Site name, description, canonical URL, locale, noindex routes.
`src/styles/base.css`	Yes, carefully	Tokens. Change the values; keep the names.
`src/components`	Rarely	The framework's components, grouped into folders by what they do — `Form`, `Interactive`, `Media`, `Typography`, `Wrapper`, `Global`, `Item`, `Utility`. Editing them makes upgrading harder. Add your own alongside instead.
`src/assets`	Always	Images, icons and logos that you import into components. Astro optimises these.
`public`	Always	Files served untouched: favicon, `og-image.jpg`, PDFs. Astro does not optimise these.

assets or public?

Anything you import goes in src/assets: Astro then resizes it, converts it to modern formats and generates the srcset for you. Anything referenced by a plain path (a favicon, a downloadable PDF, a social share image) goes in public and is served exactly as it is.

The stylesheets

global.css imports the other three in a fixed order and declares the cascade layers. You will rarely open it. base.css holds the tokens and themes and is the one you will actually change. patterns.css and utilities.css are the shared classes. The cascade explains how the four fit together.