Accessible Astro Starter

Introduction

The Accessible Astro Starter is a ready-to-use, SEO and accessibility-friendly blogging theme. It provides a solid foundation with numerous accessible components, Tailwind CSS integration, and example pages including a dynamic blog, 404 page, and MDX support.

GitHub RepositoryLive Demo

Key features

• Built on Astro 5.0
• Tailwind CSS integration
• Markdown and MDX support with examples included
• Excellent Lighthouse/PageSpeed scores
• ESLint with strict accessibility settings
• Prettier integration with plugins for Astro and Tailwind
• View Transitions support
• Dynamic blog with pagination and breadcrumbs
• Custom 404 error page

Accessibility features

• Semantic HTML landmarks (header, main, footer, nav, etc.)
• Proper heading hierarchy
• ARIA attributes for enhanced screen reader support
• Keyboard-accessible navigation with dropdown support
• Skip links for main menu and content
• Dark mode with system preference detection
• Focus indicators that work on all backgrounds
• Reduced motion preferences support
• Screen reader only text utilities
• Accessible components like Accordions, Breadcrumbs, Modals, and more

Best practice

The theme follows WCAG guidelines and includes ESLint rules to help maintain accessibility standards in your code.

Getting started

1. Clone the repository:

   git clone https://github.com/incluud/accessible-astro-starter.git

2. Install dependencies:

   npm install

3. Start development server:

   npm run dev

4. Open your browser: Visit http://localhost:4321 to see your site in action.

GitHub template

The starter is also available as a GitHub template. You can use it to create a new project by clicking the “Use this template” button in the repository.

Project structure

The starter follows a clear and organized structure:

• Directorypublic/

  • Directoryfonts/

    • …
  • … // Other assets
• Directorysrc/

  • Directoryassets/

    • Directoryimg/ // Contains the logo

      • …
    • Directoryscss/

      • Directorybase/ // Core styles and utilities

        • …
  • Directorycomponents/

    • CallToAction.astro
    • ContentMedia.astro
    • Counter.astro
    • Feature.astro
    • Footer.astro
    • Header.astro
    • Hero.astro
    • Navigation.astro
    • ResponsiveToggle.astro
    • SiteMeta.astro
  • Directorylayouts/

    • DefaultLayout.astro
    • MarkdownLayout.astro
  • Directorypages/

    • Directoryblog/

      • […page].astro // Dynamic blog pages
      • [post].astro // Individual post pages
    • 404.astro
    • accessible-astro-components.astro
    • index.astro
    • markdown-page.md
    • mdx-page.mdx
• package.json
• astro.config.mjs
• tailwind.config.js

Available commands

Command	Action
npm install	Install dependencies
npm run dev	Start dev server at localhost:4321
npm run build	Build for production
npm run preview	Preview production build

Components

The starter includes several pre-built accessible components:

• CallToAction.astro - Styled block with a button
• ContentMedia.astro - Content with media layout
• Counter.astro - Icon and number counter
• DarkMode.astro - Theme toggle with system preference
• Feature.astro - Feature highlight component
• Footer.astro - With customizable content
• Header.astro - With responsive navigation
• Hero.astro - Hero section component
• Navigation.astro - Keyboard accessible dropdown navigation
• ResponsiveToggle.astro - Mobile navigation toggle
• SiteMeta.astro - SEO meta component
• SkipLinks.astro - For keyboard users

View transitions

This theme supports Astro’s View Transitions. Please review the Astro documentation for more information.

Customization

Styling

The theme uses Tailwind CSS with additional SCSS utilities. Customize your theme in the following files:

• Directorysrc/

  • Directoryassets/

    • Directoryscss/

      • Directorybase/

        • _reset.scss // CSS reset
        • _breakpoints.scss // Media queries
        • _buttons.scss // Button styles
        • _colors.scss // Color system
        • _font.scss // Typography
        • _outline.scss // Focus styles

Components

Extend or modify existing components in the src/components directory:

src/components/Header.astro

---
import Navigation from './Navigation.astro'
---

<header>
  <Navigation />
  <!-- Add your custom header content -->
</header>

Contributing

1. Fork the repository on GitHub

2. Create a new branch:

   git checkout -b feat/your-feature-name

3. Make your changes and commit them:

   git commit -m "Add some feature"

4. Push to your fork:

   git push origin feat/your-feature-name

5. Open a Pull Request on GitHub

Getting help

If you find any issues or have questions, please open an issue on GitHub or start a discussion in the repository. You can also reach out to the Astro community on Discord.