What is included in this template?
Overview
Section titled “Overview”The Astro Performance Starter gives you a production-ready foundation focused on performance, accessibility, and DX. Phase 5 (“UI Component Library - MVP”) is now complete, delivering essential UI components alongside the foundational site structure.
What’s included in this template
Section titled “What’s included in this template”| Feature | Path | Notes |
|---|---|---|
| Base layout | src/layouts/BaseLayout.astro | SEO props, OG/Twitter tags, font pre-loading, ViewTransitions, Header, Footer, SkipLink slots. |
| Header | src/components/structural/Header.astro | Sticky, responsive shell with placeholder nav & logo. |
| Footer | src/components/structural/Footer.astro | Dynamic copyright year. |
| 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. |
| Demo landing page | src/pages/examples/landing.astro | Shows basic component usage. |
| Global font setup | @fontsource-variable/inter | Preloaded WOFF2 assets & CSS vars. |
| Security headers | public/_headers | CSP, HSTS, referrer-policy, etc. |
| Robots rules | public/robots.txt | Default allow + sitemap reference. |
| Favicon | public/favicon.svg, public/favicon.ico, public/apple-touch-icon.png | Replace with your own brand assets. |
| Mobile menu island | src/components/islands/MobileMenuToggle.tsx | Progressive enhancement; header wiring next. |
| TypeScript types | src/types/ | Navigation types and auto-generated content types. |
| Project assets | src/assets/logo.svg | Optimized logo asset for branding. |
UI Components (Phase 5 - Complete)
Section titled “UI Components (Phase 5 - Complete)”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. |
Link styling: Basic commented-out styles provided in src/styles/global.css - customize as needed or create Link component using provided documentation patterns.
Development Tools & Scripts
Section titled “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). |
| Git hooks | .husky/pre-commit | Pre-configured commit hooks with lint-staged. |
| Vitest testing | vitest.config.ts | Testing framework configuration. |
AI Development Context
Section titled “AI Development Context”| Feature | Path | Purpose |
|---|---|---|
| Windsurf AI rules | .windsurfrules | AI assistant configuration for optimal development patterns. |
| AI rules template | airules.example | Template for customizing AI development context. |
| Comprehensive docs | src/content/docs/ | Complete implementation guides, patterns, and ADRs for AI context. |
Configuration Files
Section titled “Configuration Files”| Config | Purpose |
|---|---|
.editorconfig | Consistent editor settings across team. |
.commitlintrc.cjs | Enforces conventional commit messages. |
.lintstagedignore | Files to skip during pre-commit linting. |
tailwind.config.ts | Tailwind with design token integration. |
tsconfig.json | Strict TypeScript configuration. |
.nvmrc | Node.js version specification. |
Running the template locally
Section titled “Running the template locally”pnpm install # install dependenciespnpm dev # start local dev server• Docs home: local only located at /src/content/docs/
• Demo homepage: http://localhost:4321/
Customizing the skeleton
Section titled “Customizing the skeleton”- Branding: update logo text in
Header.astroand swappublic/favicon.svg. - Navigation: edit links in
Header.astroand wire the mobile menu panel. - Pages: start new pages under
src/pages/or copy the demo landing page. - SEO defaults: change
siteTitleinsideBaseLayout.astro.
Excluded by default
Section titled “Excluded by default”| Item | Reason |
|---|---|
.github/FUNDING.yml | Funding links vary; add your own if desired |
| Documentation-specific files | Markdown linting configs, frontmatter validation scripts removed for general use |
Next phases
Section titled “Next phases”Phase 5 is complete! ✅ All MVP UI components are implemented and ready to use.
Up next: Phase 6 connects content collections for managing blog posts, projects, and structured data. Follow the implementation guides for step-by-step progress on remaining phases.