Guide

Project conventions

Organize pages, sections, reusable components, translations and styles in the generated project.

Compose pages from sections

The project follows page → layout → section → reusable component:

  • src/pages owns routes, route data and the section instances for each page.
  • src/layouts/Main.astro owns the document, metadata and main landmark.
  • src/sections owns complete page areas and their specific content or behavior.
  • src/components contains reusable pieces shared across sections.

A typical section composes Section > Box > content components. Section provides semantics and vertical spacing; Box provides content width and inline gutters. A section-specific child stays beside its section, even if it has its own file. Reusable components keep their source, supporting scripts/styles and English README together in one folder.

Keep behavior with its owner

Route identity and link appearance are separate. Link’s optional currentMatch can mark an exact page or a parent section on descendant routes, even for a plain link with a custom design. It preserves explicit aria-current and adds no browser controller. Localized home roots stay exact-only. Use the most specific current entry in a navigation set and reuse the Link resolver in an existing browser owner when dynamic navigation needs updates.

Use arrow functions by default. Keep client setup, listeners and cleanup beside the component or section that needs them. Prefer Astro’s native APIs and the installed packages before adding another abstraction. An exception to arrow functions should come from a real API requirement, such as Google’s command queue needing its own arguments object.

Choose npm, pnpm or Bun for your project dependencies and Node.js or Bun for scripts. Keep the recorded manager, generated commands and lockfile consistent. Later additions respect those choices. The maintainer repository uses pnpm/Bun; that development workflow is not a requirement for consumer projects.

Style through the shared configuration

src/styles/tailwind.css owns Tailwind 4 configuration and design tokens. Use its utilities for composition and appearance, and keep component selectors with the component when a native control or scoped behavior needs them. Use rem for authored CSS lengths and preserve the project’s responsive breakpoints, visible focus and reduced-motion behavior. Fonts come from local Fontsource imports.

Put visible copy in dictionaries

Visitor-facing copy, metadata, accessible labels and feedback belong in src/i18n/dictionaries/<locale>/<domain>. A domain has an index.ts for values and a types.ts for its contract; locale indexes compose the domains.

Regular Astro components read Astro.currentLocale themselves. Pass the locale explicitly across isolated server boundaries that cannot derive the parent page’s locale. Before connecting translated CMS slugs, read src/i18n/localized-content.md and share the real destination mapping between language navigation and SEO.

For known static pages, declare stable names in src/config/routes.ts and put actual URLs in each src/i18n/dictionaries/<locale>/routes.ts. These tables are the shared page inventory; route-tables.ts registers them and routeEntries(locale) exposes available destinations. Use null for unavailable translations. Keep the names separate from translated labels and use Astro’s URL helpers for formatting. Dynamic records still need real translation relationships; do not infer translated slugs by replacing prefixes or appending the old slug to another language’s section URL.

Let card content determine the layout

Comparable cards start their editorial stack at the top. In a stacked image and caption card, use an intrinsic media row and a remaining-space caption row, such as grid-template-rows: auto 1fr. Reserve the image geometry and preserve its crop and radius. A flex-column caption can pin an attribution or action group to the bottom with margin-block-start: auto.

Keep this layout with the section or its private card. Avoid fixed text heights, arbitrary minimum heights, clamping or shorter translations to hide alignment problems. Balance editorial headings selectively. Test short and long content, wrapped authors, long buttons and delayed provider data at 320, 390, 768 and 1440 CSS viewport widths, in both themes and at 200% text zoom. Check first rows, action insets, image boundaries, focus, overflow and any carousel loop seam. The generated .agents/memory/frontend-conventions.md contains the CSS recipe.

When the main card link represents the complete item, the card owner can reflect its :focus-visible state on the card with :has(). Keep the native link as the tab stop and secondary controls independently focused; do not add wrapper tabindex or nest controls. Check outline contrast/clipping for initial, appended, cloned and history-restored cards.

Keep incremental lists under one owner

For simple DOM cards added after an Action or API read, the owning Astro component can also render a native <template> for the browser to clone and fill with validated text/attributes. Keep one markup and formatting owner. Preserve scoped attributes, unique IDs and labels; cloning does not copy event listeners or mount client components. Use the existing controller’s delegation or setup/cleanup instead of building a second string renderer or a parallel fetch path.

Prefer native history and BFCache for list-detail returns. If a paginated list requires reconstruction, keep it as a list-owned enhancement with stable item identity, bounded/expiring navigation intent and allowlisted query context. Reuse retained DOM first, limit replay requests/time, and support cancellation, disabled storage and retry after errors. Restore focus and scroll without overriding user interaction. The starter installs no catalogue cache or restoration controller.

Add reveal only where the section needs it

Generated projects include a copyable, opt-in recipe in .agents/memory/reveal-recipe.md; it adds no mandatory animation dependency or installed integration. See its complete source and acceptance matrix.

Natural HTML stays visible without JavaScript. The first observer report only prepares unseen targets still below the viewport. Initially visible or passed content stays natural, and completed targets never replay on reverse scrolling. The recipe uses opacity and individual translate with no default stagger, exposes focused/hash-target content immediately, and cancels effects when reduced motion is enabled. Its section owner disposes navigation/HMR effects and preserves BFCache state. Deferred Server Island content needs its own explicit mount and cleanup owner after the real content arrives.

Each animated property has one owner. Do not apply competing reveal motion to Ticker tracks, Drawer panels, parallax targets or nested reveal ancestors. Use the recipe’s regression matrix before adapting it to a different lifecycle.

Maintain the generated project

The copied source belongs to your project. Edit it to fit the site’s requirements. The installer can add missing integrations; future source changes from this repository are reviewed separately. See updating a project for Astro and dependency maintenance.

Generated .agents contains portable conventions, selected skills and fresh project context. Update it as decisions change. Keep component usage documentation beside the component and keep agent context out of public assets.

These are distribution conventions. Use Astro’s components, layouts and styling guide for the underlying framework APIs.