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, <ClientRouter /> view transitions, 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. |
| Showcase page | src/pages/showcase.astro | Shows basic component usage. |
| 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 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. |
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
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 |
|---|---|---|
| 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
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. |
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: 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
Section titled “Customizing the skeleton”- Branding: swap
public/logo.svgandpublic/favicon.svg, and update the logoalttext inHeader.astro. - Navigation: edit links in
src/content/navigation/header.json(the header and mobile menu read from it). - Pages: start new pages under
src/pages/or copy the showcase page. - SEO defaults: change
siteMetadatainsidesrc/config.ts.
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 composes page sections — heroes, feature grids, and testimonials — from the component 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 on remaining phases.