astro-gov-starter

astro-gov-starter is an Astro 6 boilerplate for government service websites, combining the U.S. Web Design System (USWDS 3.x), Section 508 / WCAG 2.1 AA accessibility defaults, English/Spanish internationalization, and CI quality gates in one static-site template.

What is astro-gov-starter?

astro-gov-starter is a production-ready Astro 6 starter template created by ctrimm for government service sites. It takes an agency name, domain, and seven USA Identifier footer links as configuration in src/config/site.ts, and outputs a fully static site to dist/ with zero client-side JavaScript. The template uses USWDS 3.x via SCSS, 20 Astro component wrappers around USWDS patterns, and content collections for services, announcements, and FAQs.

Key Features

• USWDS-native design — The official USWDS 3.x design system is imported directly through SCSS, with no reimplementation; component wrappers live in src/components/uswds/.
• Accessibility defaults — Skip nav, landmarks, and focus management are built in; the USA Banner and USA Identifier components appear on every page, satisfying Section 508/WCAG 2.1 AA.
• 20 USWDS components — Astro wrappers for Alert, Accordion, Breadcrumb, CallToAction, Footer, Header, Hero, Pagination, ProcessList, Search, ServiceCard, SideNav, StepIndicator, SummaryBox, Tag, USABanner, and USAIdentifier, previewable at /internal/components/.
• i18n for English and Spanish — Each page is written once in a [...lang] dynamic route and renders for both / and /es/; adding French requires editing astro.config.mjs, adding a fr.json translation file, and updating each page's copy object.
• Pagefind static search — Self-hosted, language-aware search at /search/ and /es/search/; the index is generated after pnpm build and Pagefind splits it by each page's language.
• CI quality gates — bash scripts/check.sh runs TypeScript, HTML validation, plain-language readability (Flesch-Kincaid grade ≤ 8), and USWDS compliance checks; CI also adds axe-core, Lighthouse, and linkinator.
• Flexible deployment — Static output works on GitHub Pages (workflow included), Cloud.gov Pages with federalist.json, Netlify, Vercel, S3, CloudFront, or Azure Blob.
• Zero client JavaScript — The built site ships no client-side JS by default; Pagefind's Wasm search is an opt-in part of the build.

Who is it for?

• State and local government agencies that need a compliant, multilingual service site without designing from scratch.
• Civic technology contractors who must deliver Section 508/WCAG 2.1 AA compliance and include the required USA Banner and Identifier footer.
• Government digital service teams managing a public-facing program hub with content collections for services, FAQs, and announcements.
• Agencies on tight deadlines that want the "Use this template" GitHub flow and a setup wizard to configure branding in minutes.

What can you do with astro-gov-starter?

• Launch a compliant agency website: Run node scripts/init-agency.mjs to set your agency name, domain, and identifier links, replace the seed content in src/content/, and deploy the static dist/ folder.
• Publish bilingual content: Write each page once and get English and Spanish routes from the same file; the header language selector becomes a dropdown once you add a third locale.
• Run a searchable program directory: Populate the services content collection and get a self-hosted Pagefind index that respects locale settings.
• Verify accessibility in CI: Push to main and let the GitHub Actions workflow run axe-core, Lighthouse, and linkinator checks with enforced thresholds (a11y = 100).

How does astro-gov-starter work?

You start from the "Use this template" button, install with pnpm install, and run node scripts/init-agency.mjs to update src/config/site.ts with agency details and the seven USA Identifier links. After replacing seed markdown content, pnpm build produces dist/ and indexes it with Pagefind. The included scripts/check.sh runs all local quality gates before you push.

FAQ

Does astro-gov-starter include a working form backend?

No. The contact form and eligibility screeners are accessible scaffolding only. You must wire the action attributes to a backend such as Formspree or your agency's form service before launch.

Is the search index available during development?

No. Pagefind search works only in a production build (pnpm build && pnpm preview); the dev server has no index. The CSP includes 'wasm-unsafe-eval' because Pagefind runs as WebAssembly, but this does not enable JavaScript eval().

Can I add a language other than Spanish?

Yes. Every page renders for each locale in the locales array. To add French, update astro.config.mjs, create src/i18n/fr.json, add fr to the Locale type and localeMeta, and add translated copy to each page's copy object.

Does GitHub Pages support custom security headers?

No. GitHub Pages ignores custom HTTP response headers, so the _headers file with X-Frame-Options, HSTS, and clickjacking protection only works on Netlify, Cloudflare Pages, or a CDN in front of Pages. The README advises using a host with header support for production government sites.

What licenses apply?

The code is MIT, and the seed content is CC0 — no rights reserved, free to adapt for any agency.