Project structure

Most of your time goes into four places: src/config/ for settings, src/i18n/ui/ for words, src/content/ for work and articles, and src/assets/ for images.

• Directorysrc/

  • Directoryassets/ photography, one folder per entry, optimised at build time

    • Directoryprojects/

      • …
    • Directoryjournal/

      • …
    • Directorystudio/

      • …
  • Directorycomponents/

    • Directorycase/ case study layouts (editorial, narrative, gallery) and their parts

      • …
    • Directorysections/ home and page sections: hero, index, results, quote…

      • …
    • Directorywork/ work grid card and empty state

      • …
    • Directoryjournal/ article card and journal index

      • …
    • Directoryui/ primitives: Media, Icon, Wordmark, LocaleSwitcher, PresetSwitcher, ThemeToggle

      • …
    • Nav.astro
    • Footer.astro
    • Seo.astro meta tags, hreflang and JSON-LD
  • Directoryconfig/

    • site.ts name, contact details, navigation, preset, currency, form endpoint
    • presets.ts the four theme presets
  • Directorycontent/ default language at the root, translations in de/ and id/

    • Directoryprojects/ one JSON file per case study

      • …
    • Directoryjournal/ one MDX file per article

      • …
    • Directoryroles/ open roles for /careers

      • …
    • Directorylegal/ privacy and imprint, Markdown

      • …
    • schema.ts Zod schemas every entry is validated against
    • taxonomy.ts disciplines, industries, authors, case layouts
  • Directoryi18n/

    • config.ts languages and the default language
    • utils.ts t(), localizePath(), formatDate() and friends
    • Directoryui/ en.ts, de.ts, id.ts: every word on the site

      • …
  • Directorylayouts/

    • BaseLayout.astro
  • Directorylib/ collection helpers with translation fallback

    • …
  • Directorypages/

    • Directory[…lang]/ every page, written once for all languages

      • index.astro
      • work.astro
      • services.astro
      • studio.astro
      • careers.astro
      • contact.astro
      • [legal].astro
      • case-study/[slug].astro
      • Directoryjournal/

        • …
    • 404.astro
    • rss.xml.ts
    • styleguide.astro the living design-system reference
  • Directoryscripts/ small TypeScript modules, no framework

    • …
  • Directorystyles/

    • tokens.css type, space, motion and layer tokens
    • fallbacks.css metric-matched fallback fonts
    • global.css base styles and component classes
  • content.config.ts
• Directorypublic/ files served as they are: favicon, og.png, robots.txt, _headers

  • …
• astro.config.mjs
• keystatic.config.ts
• tailwind.config.mjs
• lighthouserc.json
• netlify.toml
• vercel.json
• wrangler.jsonc

How a page is put together

1. A route in src/pages/[...lang]/ runs once per language. It reads the language with useLocale(Astro) and its words with t(locale).
2. It loads content through a helper in src/lib/, which picks the translation for that language or falls back to English.
3. It renders sections from src/components/ inside BaseLayout, which adds the navigation, footer, theme script and SEO tags.
4. Tailwind classes in the components read the tokens and the active preset, so the same markup works in every preset and in dark mode.

The styleguide

Run the dev server and open /styleguide. It renders every token, preset and component in both themes. It is left out of the sitemap and marked noindex, and robots.txt disallows it.