Astro Build Standards docs

New-client setup runbook#

[runbook]Reference

Phase numbers map to lifecycle.

1. Scaffold

  1. Create the repo from the starter's GitHub template. Leave starterVersion in package.json exactly as inherited — it records the baseline this build was cut from and is never bumped in a client repo (structure.git).
  2. Update package.json name and README; confirm the structure.gate scripts.
  3. Fill in src/data/site.ts (name, url, description, ogImage, logo, socials). astro.config.mjs reads the URL from it (seo.identity). The domain can stay the placeholder while previewing — the build warns, and checklist.pre-launch is what blocks on it at cutover.
  4. Add host config for the chosen target (deploy.static). Add public/_headers and, for a migration, public/_redirects.
  5. Flip public/robots.txt from the blocked starter default to the allow policy commented directly beneath it, and set the Sitemap: host (seo.ai-crawlers). The starter ships Disallow: / because a template shouldn't be crawled; a client site must not. Check src/pages/404.astro is in place.
  6. Add .env keys; commit .env.example (structure.env). Write the per-client agent brief (structure.agent-brief).
  7. Set up preview/staging protection now, not at launch (seo.staging).

2. Design-system intake

  1. Fill every --color-* role in global.css @theme, for every theme the project ships. Add brand-named accents separately; map --color-intent to the primary.
  2. Decide the theme set and register the @custom-variants.
  3. Set per-client decisions (tokens.per-client): radius stance, depth, accents.
  4. Wire fonts (perf.fonts); set --font-heading/-sans/-mono. Tune the fluid type clamps. 11b. Answer DESIGN.md. It ships as prompts, not content — work through every one, record the decisions from steps 8–11 with the reasoning behind them, and delete each prompt as you replace it. Write project rules normatively ("never…") rather than descriptively ("cards have…"). No values, and no repeating house rules from docs/rules/ (tokens.design-doc).

3. Componentize

  1. Build pages from starter primitives; keep components/ flat. New components → templates template + checklist.component.
  2. Keep the full starter component set — don't delete unused components (principles, principle 10). Production stays lean via route gating and tree-shaking. Remove only deprecated or broken code.

4. Content & SEO

  1. Define collections in content.config.ts (lean; reference() taxonomies; image() for content images). Keep the content-source seam (content.source-seam).
  2. Author lib/schema.ts graphs; pass jsonLd from pages.
  3. Set per-page title/description/image/noindex. Extend the sitemap filter.

5. Optimize & QA

  1. Import images via astro:assets; measure against perf.budgets budgets.
  2. Run checklist.page, checklist.seo and checklist.a11y on every template.

6. Launch

  1. Run checklist.pre-launch. Deploy to the chosen production host. Verify production. Hand off.