What is included in this template?

Overview

The Astro Performance Starter gives you a production-ready foundation focused on performance, accessibility, and DX. The Foundation tier (Phases 0-4) ships complete — design system, content schemas, tooling, and the skeleton layout — together with the UI component set and demo pages listed below. Phases 5-12 (the Build and Polish tiers) are the active build path you work through for your own site.

What’s included in this template

Feature	Path	Notes
Base layout	src/layouts/BaseLayout.astro	SEO props, OG/Twitter tags, font pre-loading, <ClientRouter /> view transitions, Header, Footer, SkipLink slots.
Header	src/components/structural/Header.astro	Sticky, responsive shell. Its nav is data-driven: it reads the navigation content collection (src/content/navigation/header.json) with getCollection() at build time, so links are content, not markup. Mobile menu is CSS-only.
Footer	src/components/structural/Footer.astro	Dynamic copyright year; links come from siteLinks / socialLinks in src/config.ts.
Skip link	src/components/a11y/SkipLink.astro	Keyboard-friendly “skip to content”.
Error pages	src/pages/404.astro, src/pages/500.astro	Custom, accessible error templates.
Showcase page	src/pages/showcase.astro	The living style guide (ADR-049): System / Color / Type / Motion / Components sections built from token-driven specimens so it cannot drift from the design system. Also the home of the two sanctioned demo islands (ADR-060).
Global font setup	Astro Fonts API (fontProviders.local() in astro.config.mjs)	Vendored WOFF2 files in src/assets/fonts/ with preloading and metric-adjusted fallbacks.
Security headers	public/_headers	CSP, HSTS, referrer-policy, etc.
Robots rules	src/pages/robots.txt.ts	Generated at build time; default allow + sitemap reference.
Favicon	public/favicon.svg, public/favicon.ico, public/apple-touch-icon.png	Replace with your own brand assets.
Preact islands	src/components/islands/	SignalsCounter.tsx (client:visible) and MotionLab.tsx (client:idle) demo islands; the mobile menu is CSS-only in Header.astro.
TypeScript types	src/types/	Navigation types (navigation.ts), homepage data types (content.ts), icon names (icons.ts), and auto-generated content-collection types.
Project assets	src/assets/logo.svg	Optimized logo asset for branding.

UI Components

Essential UI primitives following atomic design patterns:

Component	Path	Purpose
Button	src/components/atoms/Button.astro	Versatile button with size/variant props. Primary foundation for interactions.
Badge	src/components/atoms/Badge.astro	Non-interactive labels for status, metrics, or categories.
Image	src/components/atoms/Image.astro	Wrapper around Astro’s Image with project defaults (AVIF, optimized sizing).
Card	src/components/molecules/Card.astro	Flexible content container with consistent spacing and styling.
Container	src/components/structural/Container.astro	Manages horizontal width and centers content across breakpoints.
Section	src/components/structural/Section.astro	Controls vertical rhythm and spacing for page sections.
Grid	src/components/structural/Grid.astro	Responsive CSS Grid with consistent gaps and breakpoint behavior.

Beyond these primitives, the template ships a full component set (30+ components):

Category	Components
Atoms (src/components/atoms/)	Icon, ThemeToggle, Tooltip, SocialLink, CounterBadge, AnimatedGradientText, CursorSpotlight, ReadingProgress, ScrollReveal, SheenEyebrow
Molecules (src/components/molecules/)	ContactForm, Dialog, Tabs, Head, PostCard, ProjectCard, ScrollSpy, SectionSeparator, ShowcaseExample, ExpandableFeatureCard, ColorTokenSwatch, PaletteBand, TypeSpecimen
Structural (src/components/structural/)	ParallaxSection (plus Header, Footer, Container, Section, Grid listed above)
MDX components (src/components/mdx/)	Figure, Grid, Callout, Blockquote, CodeFromFile, Link
Layouts & pages	BlogLayout.astro and ProjectLayout.astro plus blog and projects pages wired to content collections

Link styling: Global link styles ship active in src/styles/global.css — an a rule applies the link color token with a visible focus ring, and prose links are themed via the Typography plugin (--tw-prose-links). Customize there or create a Link component as needed.

Development Tools & Scripts

Tool	Path/Config	Purpose
Design tokens	tokens/base.json, tokens/semantic.json	Complete design system with build script.
Token builder	scripts/src/build-tokens.ts	Converts JSON tokens to CSS variables and Tailwind config.
Performance baseline	scripts/src/baseline-performance.ts	Lighthouse score tracking and budgets.
Contrast validator	scripts/src/validate-contrast.ts	WCAG AA accessibility validation.
Budget tracking	scripts/src/track-performance-budgets.ts	Performance budget enforcement.
Biome linting	biome.json	Fast linting and formatting (replaces ESLint + Prettier).
Markdown linting	.markdownlint-cli2.jsonc	pnpm run lint:md over **/*.md and **/*.mdx; part of quality and quality:ci, and runs with --fix on staged Markdown via lint-staged.
Git hooks	.husky/ (pre-commit, commit-msg, pre-push)	Pre-configured hooks: lint-staged on commit, commitlint on the message.
Vitest testing	vitest.config.ts	Testing framework configuration.

AI Development Context

Feature	Path	Purpose
Layered AI constitution	CLAUDE.md, AGENTS.md	Halt-on-violation rules and generated agent instructions.
Comprehensive docs	docs/	Complete implementation guides, patterns, and ADRs for AI context.

Configuration Files

Config	Purpose
.editorconfig	Consistent editor settings across team.
.commitlintrc.cjs	Enforces conventional commit messages.
.lintstagedignore	Files to skip during pre-commit linting.
tsconfig.json	Strict TypeScript configuration.
.nvmrc	Node.js version specification.

Running the template locally

pnpm install   # install dependencies
pnpm dev       # start local dev server

• Docs home: the docs/ directory ships in the repo for local and AI-context reference; the same documentation is published at docs.clownware.org/astro/ • Demo homepage: http://localhost:4321/

Customizing the skeleton

1. Branding: swap public/logo.svg and public/favicon.svg, and update the logo alt text in Header.astro.
2. Navigation: edit links in src/content/navigation/header.json (the header and mobile menu read from it).
3. Pages: start new pages under src/pages/ or copy the showcase page.
4. SEO defaults: change siteMetadata inside src/config.ts.

Excluded by default

Item	Reason
.github/FUNDING.yml	Funding links vary; add your own if desired

Next phases

The roadmap in docs/README.md (synced by pnpm run roadmap:update) marks Phases 0-4 complete — the Foundation tier everyone starts from. Phases 5-12 are the active build path even though the primitives above already ship: the Phase 5: Components guide is where you scope which further components your site needs (Essential / Recommended / Advanced), and Phase 6 composes page sections — heroes, feature grids, and testimonials — from that library. Content collections for blog posts, projects, bio, and experience are already implemented and wired in. Follow the implementation guides for step-by-step progress.