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. Version 4.0.0 introduces a complete design system overhaul with OKLCH colors, Atkinson Hyperlegible font, and significant accessibility improvements.

GitHub RepositoryLive Demo

Key features

• Built on Astro 5.7.5
• Tailwind CSS 4.0 integration
• Modern OKLCH color system with light/dark mode
• Atkinson Hyperlegible font for improved readability
• 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 using AJAX fetch
• Enhanced portfolio page with rich media support
• Custom 404 error page
• TypeScript interfaces and proper prop typing

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
• Color Contrast Checker component for accessibility testing
• Modern CSS with logical properties

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
  • Directorycontent/

    • Directoryprojects/

      • project-01.md
      • project-02.md
      • project-03.md
      • project-04.md
      • project-05.md
      • project-06.md
      • project-07.md
  • Directorylayouts/

    • DefaultLayout.astro
    • MarkdownLayout.astro
  • Directorypages/

    • Directoryblog/

      • […page].astro // Dynamic blog pages
      • [post].astro // Individual post pages
    • Directoryportfolio/

      • […page].astro
      • [project].astro
    • 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, with several new additions in version 4.0.0:

Core 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

New in 4.0.0

• ColorContrast.astro - Accessibility testing component for color contrast
• PageHeader.astro - Consistent page titles component
• Logo.astro - Standardized branding component
• ExternalLink.astro - Link with proper external attributes
• BlockQuote.astro - Content citation component
• BreakoutImage.astro - Full-width image component
• SocialShares.astro - Blog post sharing component

View transitions

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

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>

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
        • _root.scss // Custom properties

OKLCH Color System

Version 4.0.0 introduces a powerful OKLCH-based color system that makes it incredibly easy to create accessible color schemes. The best part? You only need to define your three brand colors, and the entire color palette is automatically generated!

Simple Brand Color Setup

:root {
  // Just set these three brand colors in hex or any format
  --brand-primary: #d648ff;   // Your primary brand color
  --brand-secondary: #00d1b7; // Your secondary brand color
  --brand-neutral: #b9bec4;   // Your neutral brand color

  // The rest of the color palette is automatically generated!
}

How it works

:root {
  // Your brand colors (these are the only ones you need to customize)
  --brand-primary: #d648ff;
  --brand-secondary: #00d1b7;
  --brand-neutral: #b9bec4;

  // Automatic generation of primary palette with 5 variations
  --color-primary-100: oklch(from var(--brand-primary) 90% c h); // Lightest
  --color-primary-200: oklch(from var(--brand-primary) 80% c h);
  --color-primary-300: oklch(from var(--brand-primary) 70% c h);
  --color-primary-400: oklch(from var(--brand-primary) 60% c h);
  --color-primary-500: oklch(from var(--brand-primary) 50% c h); // Darkest

  // Secondary color palette is generated the same way
  --color-secondary-100: oklch(from var(--brand-secondary) 90% c h);
  // ... and so on

  // Neutral palette for text, backgrounds, etc.
  --color-neutral-100: oklch(from var(--brand-neutral) 100% 0 0); // White
  --color-neutral-200: oklch(from var(--brand-neutral) 95% c h);
  // ... through to:
  --color-neutral-900: oklch(from var(--brand-neutral) 15% c h); // Near black

  // Automatic light/dark mode handling
  --foreground-color: light-dark(var(--color-neutral-800), var(--color-neutral-100));
  --background-color: light-dark(var(--color-neutral-100), var(--color-neutral-900));
  --link-color: light-dark(var(--color-primary-400), var(--color-secondary-100));
  // ... and more
}

// Dark mode is handled automatically
.darkmode {
  color-scheme: dark;
}

Example customization

// In your _root.scss or a new SCSS file

:root {
  // Just update these three values to transform your entire theme
  --brand-primary: #4a6cf7;    // Blue
  --brand-secondary: #f7724a;  // Orange
  --brand-neutral: #94a3b8;    // Slate

  // All of your theme colors will automatically adjust!
}

The magic of this system is how it leverages OKLCH color transformations to create consistent, harmonious color palettes with proper contrast for accessibility. OKLCH (Lightness, Chroma, Hue) is a perceptually uniform color space that makes it easier to create accessible color combinations.

Easy theming

By changing just three brand colors, you can completely transform your site’s theme while maintaining accessibility. The system automatically handles light/dark mode, contrast, and creates a full color palette with multiple shades.

Verify accessibility

While OKLCH helps create better color palettes, always verify your customized colors with the Color Contrast Checker component included in the starter. Accessibility is not automatically guaranteed when customizing colors, especially for text and interactive elements that need to meet WCAG contrast requirements.

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.