AstroDemo
AstroDemo
Open source starter

Built for the modern web.

AstroDemo is a demonstration site that shows how to build a fast, accessible, content-focused website with the Astro framework — zero JavaScript shipped by default.

Project goals

  • Zero unnecessary JavaScript

    Pages are pure HTML and CSS at load time. Every KB of JavaScript is a deliberate choice, not a framework default.

  • Accessibility by default

    WCAG 2.1 AA out of the box: skip links, semantic HTML, keyboard navigation, and verified contrast ratios.

  • TypeScript throughout

    Strict mode, no any, typed component props. The compiler catches issues before they reach production.

  • AI-friendly structure

    Conventions, slash commands, and CLAUDE.md make this a ready-made launchpad for AI-assisted development workflows.

Tech stack

Framework
Astro 4 — static output, no server runtime required
Language
TypeScript in strict mode throughout every file
Styling
CSS custom properties for design tokens; scoped styles per component
Content
Markdown via Astro Content Collections, validated with Zod
Package manager
npm
Deploy
GitHub Actions → GitHub Pages (zero-config CI/CD)

Development principles

  1. Read before you write

    Understand existing code before modifying it. Every file has context and intent — ignoring it creates technical debt.

  2. Minimal and focused changes

    Only add what the task requires. No speculative abstractions, no future-proofing, no unnecessary refactors alongside bug fixes.

  3. Performance is a feature

    Every dependency, every script tag, every image has a cost. We measure, we question, and we only pay for what genuinely helps users.

  4. Accessibility is non-negotiable

    Not a checklist item — a baseline. WCAG AA compliance, keyboard navigation, and screen reader support are required, not optional.

  5. Build quality in from the start

    npm run check and npm run build must pass with zero errors before any commit reaches the repository.

MIT License

AstroDemo is released under the MIT License. Use it, fork it, build on it — for personal projects, client work, or commercial products. No attribution required, though it's always appreciated.