Astro Implementation Guide - Master Index

Quick Start

This guide provides a structured approach to building high-performance Astro sites through a single progressive path with three natural tiers:

• Foundation (Phases 0–4): Core setup — everyone starts here
• Build (Phases 5–8): Make it yours — components, content, QA
• Polish (Phases 9–12): Production-harden — performance, deployment, docs

Work through phases sequentially and stop when you’ve reached your goals. See ADR-033 for the rationale behind this model (it replaced the earlier MVP/Showcase dual-track model).

Phase Dependency Map

Foundation (everyone)
  Phase 0: Foundation
    → Phase 1: Content Architecture
    → Phase 2: Design System
    → Phase 3: Tooling
    → Phase 4: Skeleton

Build (make it yours)
    → Phase 5: Components
    → Phase 6: Sections
    → Phase 7: Content
    → Phase 8: QA

Polish (production-harden)
    → Phase 9: Performance
    → Phase 10: Deployment
    → Phase 11: Documentation
    → Phase 12: Post-Launch

Tier Overview

Foundation (Phases 0–4) — Everyone does these

Pre-configured in the template. Delivers a deployable site skeleton with no content.

• Astro + TypeScript + Tailwind + Biome
• Content Collections schemas
• Design tokens system
• Base layouts and structural components
• CI pipeline

Build (Phases 5–8) — Where you make it yours

Scope each phase to your project’s actual needs using the Essential / Recommended / Advanced labels within each guide.

• UI component implementation
• Page sections and layouts
• Content creation
• Quality assurance

Polish (Phases 9–12) — Production hardening

Stop here when you need an enterprise-grade deployment.

• Performance optimization and budget enforcement
• Deployment configuration
• Documentation and AI context
• Post-launch monitoring and maintenance

Phase Overview

“Completed” vs “Active” is from your perspective as a cloner, not the template’s. This template already ships a fully-built reference implementation of every phase (40+ components, content collections, an e2e suite, performance budgets, CI, and deployment config). The Foundation phases below are marked “Complete” because they’re shared infrastructure you inherit as-is; the “Active” phases are the customization work you do to make the site yours (your components, your content, your QA pass). Read each active phase as a guided walkthrough, using the shipped implementation as the worked example.

✅ Completed Phases (Foundation)

Phase	Name	Scope	Status
0	Foundation	Essential	✅ Complete
1	Content Architecture	Essential	✅ Complete
2	Design System	Essential	✅ Complete
3	Tooling	Essential	✅ Complete
4	Skeleton	Essential	✅ Complete

🚧 Active Phases (Build)

Phase	Name	Scope	Effort	Critical Path
5	Components	Essential → Advanced	2-4 days	⚡
6	Sections	Essential → Advanced	2-3 days	⚡
7	Content	Essential	3-5 days	📝
8	QA	Essential → Advanced	1-3 days	✓

🚧 Active Phases (Polish)

Phase	Name	Scope	Effort	Critical Path
9	Performance	Essential	1-2 days	✓
10	Deployment	Essential	1 day	🚀
11	Documentation	Recommended	1-2 days	📚
12	Post-Launch	Recommended	1 day	🎯

Getting Started

1. Review Tech Stack: Check technology choices
2. Understand Budgets: Study performance targets
3. Set Up Structure: Follow directory layout
4. Begin Phase 0: Start with foundation decisions
5. Stop when done: Each tier has a clear deliverable — ship when it meets your goals

Additional Resources

📖 Topic Guides

• Accessibility Guide - WCAG AA compliance patterns
• Components Guide - Component architecture best practices
• Content Model Guide - Content Collections patterns
• Image Optimization Guide - Performance-first image strategies
• Responsive Design Guide - Mobile-first patterns and breakpoint usage
• Testing Strategy Guide - QA and testing approaches
• Rollback Strategies Guide - Deployment safety patterns

💻 Code Examples

Each active phase includes practical code examples:

• Phase 5 Examples - Component implementations
• Phase 6 Examples - Section layouts
• Phase 7 Examples - Content patterns
• Phase 8 Examples - QA testing code
• Phase 9 Examples - Performance optimizations
• Phase 10 Examples - Deployment configurations
• Phase 12 Examples - Post-launch monitoring

Phase 11 (Documentation) has no separate examples page — its templates are inline in the phase guide.

📚 Reference Documentation

• Tech Stack - Complete technology overview
• Directory Structure - Project organization
• Budgets & Guardrails - Performance targets
• Portfolio Checklist - Curated scope items for portfolio-quality sites
• Optional Analytics - Tracking implementation
• Table Format Guide - Documentation standards

Common Patterns

• Islands Architecture - When to add interactivity
• Content Collections - Advanced content patterns
• Performance Patterns - Optimization techniques
• Component Patterns - Reusable UI patterns

Scope Decision Matrix

Need	Essential	Recommended	Advanced
Interactivity	Static HTML + CSS	CSS + minimal JS for simple state	Preact islands where justified
Testing	Manual checklist	Playwright critical paths	Full e2e suite + a11y checks + visual regression
Components	Core UI only	Extended component library	/showcase style guide + full documentation
Documentation	README + basics	AI context updated	Comprehensive guides
Monitoring	Basic uptime	Lighthouse CI	RUM + error tracking

Support & Updates

• Changelog: See CHANGELOG.md in the repository root
• Issues: Create an issue in your project repo
• Updates: Check monthly for Astro updates
• Community: Astro Discord