Astro Build Standards

Everything that governs how a Miscreants Astro site is built. New here? Start with the Workflow router — find your task, read only the modules it needs.

Start here

OverviewThe map — every doc and what it covers.WorkflowThe router: task → modules to read → verification tier.

Rules

The only place a rule is stated.

PrinciplesThe ten principles, rule tiers, where each kind of doc lives.StructureRepo layout, naming, aliases, scripts, env & secrets, git lineage.Tokens & stylingToken model, theme contract, typography, layout, motion.ComponentsPages → sections → components, SectionMain, props, slots, scripts, forms.Component templatesThe three starting points: static, interactive, polymorphic.SEO & headSite identity, Layout contract, Seo.astro, JSON-LD, sitemap.AccessibilityNative-first semantics, keyboard, focus, measurable thresholds.ContentCollections, the content-source seam, registries, copy quality.PerformanceImages, fonts, CSS, prefetch, third-party, canvases, budgets.DeploymentHosts, redirects, headers, demo-route gating.

Checklists

What reviewers gate on.

All checklistsWhich gate applies when.ComponentAny new or changed component.PageA page is finished.SEOPer page or template.AccessibilityPer page.Pre-launchBefore going live — runs as the launch skill.

Process & state

LifecycleThe six phases of a client engagement.RunbookStep-by-step new-client setup, mapped to those phases.GuardrailsThe gates, the shipped skills, local-development notes.ConformanceWhere the starter does not yet meet its own Required rules.RoadmapPrioritized follow-up work.PlanLonger-horizon direction notes — explicitly not rules.ChangelogWhat changed between versions of the standard.

Reference

How-to: contact form emailWiring a contact form to an email binding.Astro for beginnersAstro onboarding — background material, not a rule source.

How this fits together

text

AGENTS.md ─────────► the contract: non-negotiables + where to go next
    │                (CLAUDE.md is a pointer to it, nothing more)
    ▼
docs/workflow.md ──► the router: task → modules → verification tier
    │
    ├──────────────► docs/rules/*.md ──────► the rules, stated once
    │                                        each carries a stable id
    │
    └──────────────► docs/checklists/*.md ─► the gates, citing those ids

Rules are cited by id, never by section number or page. Each rule declares one beside its heading:

### Client-side scripting
<!--rule: components.scripting | tier: required-->

Write [components.scripting] anywhere in the repo to cite it. Ids survive rules moving between files, which section numbers did not. npm run docs:build keeps the generated rule-links footer in each file current so every citation renders as a working link; npm run check fails on a citation to an id that doesn't exist.

bash

npm run docs:build      # refresh the rule-link footers
npm run docs:check      # citations, links, ids, footers

Generated from docs/*.md in astro-miscreants-starter-v1. The markdown remains the source of truth — regenerate after changes.