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. The theme features a centralized configuration system, an integrated command launcher for keyboard-driven navigation, and comprehensive accessibility preference toggles.

GitHub RepositoryLive Demo

Key features

• Built on Astro 5.16+
• Tailwind CSS 4.1+ integration
• Centralized theme configuration via theme.config.ts
• Command launcher with keyboard navigation (Cmd/Ctrl+K)
• Dynamic theme colors configurable from a single config file
• Modern OKLCH color system with light/dark mode
• Improved SEO with astro-seo package
• 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
• 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
• Command launcher with full keyboard navigation (Cmd/Ctrl+K)
• Skip links for main menu and content
• Dark mode with system preference detection
• High Contrast mode toggle for enhanced visual clarity
• Reduced Motion mode toggle respecting user preferences
• Focus indicators that work on all backgrounds
• 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 and social preview

      • …
    • Directoryscss/

      • Directorybase/ // Core styles and utilities

        • …
  • Directorycomponents/

    • CallToAction.astro
    • ContentMedia.astro
    • Counter.astro
    • Feature.astro
    • Footer.astro
    • Header.astro
    • Hero.astro
    • LauncherConfig.astro // Command launcher configuration
    • Navigation.astro
    • NavigationItems.astro // Dynamic navigation from config
    • ResponsiveToggle.astro
  • Directorycontent/

    • Directoryprojects/

      • project-01.mdx
      • … // Project content files
  • Directorylayouts/

    • DefaultLayout.astro // Includes SEO via astro-seo
    • MarkdownLayout.astro
  • Directorypages/

    • Directoryblog/

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

      • […page].astro
      • [project].astro
    • 404.astro
    • accessible-components.astro
    • accessible-launcher.astro // Launcher demo page
    • accessibility-statement.mdx
    • index.astro
    • markdown-page.md
    • mdx-page.mdx
  • Directoryutils/

    • defineThemeConfig.ts // Theme config utility
• theme.config.ts // Centralized theme configuration
• package.json
• astro.config.mjs

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:

Core Components

• CallToAction.astro - Styled block with a button
• ContentMedia.astro - Content with media layout
• Counter.astro - Icon and number counter
• Feature.astro - Feature highlight component
• Footer.astro - With customizable content
• Header.astro - With responsive navigation and launcher
• Hero.astro - Hero section component
• Navigation.astro - Keyboard accessible dropdown navigation
• NavigationItems.astro - Dynamic navigation items from theme config
• ResponsiveToggle.astro - Mobile navigation toggle

Content Components

• ColorContrast.astro - Accessibility testing component for color contrast
• PageHeader.astro - Consistent page titles component
• Logo.astro - Standardized branding component
• BlockQuote.astro - Content citation component
• BreakoutImage.astro - Full-width image component
• SocialShares.astro - Blog post sharing component
• FeaturedPosts.astro - Showcase featured blog posts
• FeaturedProjects.astro - Showcase featured projects

Launcher

• LauncherConfig.astro - Command launcher configuration with preferences, navigation, blog posts, projects, and socials

View transitions

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

Theme Configuration

The starter uses a centralized theme configuration system. All site-wide settings are managed in a single theme.config.ts file at the project root.

Basic Configuration

theme.config.ts

import { defineThemeConfig } from '@utils/defineThemeConfig'
import previewImage from '@assets/img/social-preview-image.png'
import logoImage from '@assets/img/logo.svg'

export default defineThemeConfig({
  name: 'My Awesome Site',
  id: 'my-awesome-site',
  logo: logoImage,
  seo: {
    title: 'My Awesome Site',
    description: 'A website built with Accessible Astro Starter',
    author: 'Your Name',
    image: previewImage,
  },
  colors: {
    primary: '#d648ff',
    secondary: '#00d1b7',
    neutral: '#b9bec4',
    outline: '#ff4500',
  },
  navigation: {
    darkmode: true,
    items: [
      // Navigation items...
    ],
  },
  socials: [
    // Social links...
  ],
})

Configuration Options

SEO Settings

seo: {
  title: 'Site Title',           // Used in <title> and OG tags
  subtitle: 'Optional Subtitle', // Appended to title when present
  description: 'Site description for SEO',
  author: 'Author Name',
  image: previewImage,           // ImageMetadata or string path
}

Theme Colors

colors: {
  primary: '#d648ff',   // Primary brand color
  secondary: '#00d1b7', // Secondary brand color
  neutral: '#b9bec4',   // Neutral/gray color
  outline: '#ff4500',   // Focus outline color
}

These colors are automatically applied as CSS custom properties and used by the OKLCH color system to generate your full color palette.

Navigation Items

navigation: {
  darkmode: true, // Show dark mode toggle
  items: [
    // Simple link
    {
      type: 'link',
      label: 'Home',
      href: '/',
    },
    // External link with icon
    {
      type: 'link',
      label: 'GitHub',
      href: 'https://github.com/...',
      icon: 'lucide:github',
      external: true,
      excludeFromLauncher: true, // Hide from command launcher
    },
    // Dropdown menu
    {
      type: 'dropdown',
      label: 'Features',
      items: [
        { label: 'Components', href: '/components' },
        { label: 'Launcher', href: '/launcher' },
      ],
    },
  ],
}

Social Links

socials: [
  {
    label: 'GitHub',
    href: 'https://github.com/yourname',
    icon: 'lucide:github',
  },
  {
    label: 'Bluesky',
    href: 'https://bsky.app/profile/yourname',
    icon: 'lucide:bot-message-square',
  },
]

Social links appear in the command launcher for quick access.

TypeScript Support

The defineThemeConfig utility provides full TypeScript support with autocompletion and type checking for all configuration options.

Command Launcher

The starter includes the Accessible Astro Launcher component - a keyboard-driven command palette for quick navigation and accessibility preferences.

Opening the Launcher

• Keyboard shortcut: Press Cmd + K (Mac) or Ctrl + K (Windows/Linux)
• Click trigger: Click the search field in the navigation bar

Features

The launcher provides quick access to:

• Preferences: Toggle Dark Mode, High Contrast, and Reduced Motion
• Navigation: All pages defined in your theme configuration
• Blog Posts: Dynamically loaded from your blog API (if configured)
• Projects: Your portfolio projects from content collections
• Socials: Links to your social profiles

Configuration

The launcher is configured in src/components/LauncherConfig.astro and automatically reads from your theme.config.ts:

src/components/LauncherConfig.astro

---
import { Launcher, LauncherList, LauncherItem, LauncherGroup } from 'accessible-astro-launcher'
import themeConfig from '@theme-config'

// Navigation items are automatically loaded from theme config
const launcherNavigationItems = themeConfig.navigation.items.flatMap((item) => {
  if (item.excludeFromLauncher) return []
  // ... processes navigation items
})
---

<Launcher id="site-launcher">
  <LauncherList>
    <LauncherGroup label="Preferences">
      <!-- Preference toggles -->
    </LauncherGroup>
    <LauncherGroup label="Navigate to">
      <!-- Navigation items from config -->
    </LauncherGroup>
    <!-- Additional groups for blog, projects, socials -->
  </LauncherList>
</Launcher>

Blog API Integration

To enable dynamic blog posts in the launcher, set the BLOG_API_URL environment variable:

.env

BLOG_API_URL=https://your-blog-api.com/posts.json

Launcher Documentation

For complete documentation on the launcher component, including all available props and customization options, visit the Accessible Astro Launcher documentation.

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

Responsive Breakpoint System

The starter includes a powerful and versatile breakpoint mixin system using modern CSS media query syntax. The system supports min-width, max-width, and range queries with predefined breakpoints or custom values.

Available Breakpoints

$breakpoints: (
  'default': 0,
  'xs': 320px,
  's': 480px,
  'm': 768px,
  'l': 1024px,
  'xl': 1280px,
  '2xl': 1536px,
  'nav': 1000px,
)

Usage Examples

Min-width (mobile-first)

// Apply styles from medium screens and up
.component {
  @include breakpoint('m') {
    font-size: 1.2rem;
    padding: 2rem;
  }
}

// Output: @media (width >= 768px) { ... }

Max-width

// Apply styles below medium screens (mobile override)
.component {
  @include breakpoint('m', 'max') {
    display: none;
  }
}

// Output: @media (width < 768px) { ... }

Range between breakpoints

// Apply styles only between medium and extra-large
.component {
  @include breakpoint('m', 'xl') {
    grid-template-columns: repeat(2, 1fr);
  }
}

// Output: @media (768px <= width < 1280px) { ... }

Custom values

// Use custom pixel values
.component {
  @include breakpoint(600px, 900px) {
    max-width: 80%;
  }
}

// Output: @media (600px <= width < 900px) { ... }

Explicit helpers

// Alternative syntax for clarity
.component {
  @include breakpoint-min('m') { }  // Min-width
  @include breakpoint-max('l') { }  // Max-width
  @include breakpoint-between('m', 'xl') { } // Range
}

Modern syntax

The breakpoint system uses modern CSS range syntax (width >= 768px instead of min-width: 768px), which is more readable and follows current CSS best practices. All modern browsers support this syntax.

OKLCH Color System

The starter includes a powerful OKLCH-based color system that makes it incredibly easy to create accessible color schemes. You only need to define your brand colors in theme.config.ts, 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.

SEO Configuration

The starter uses the astro-seo package for SEO management, integrated directly in DefaultLayout.astro. Pass SEO props to any page through the layout:

---
import DefaultLayout from '../layouts/DefaultLayout.astro'
---

<DefaultLayout
  title="My Page"
  description="Page description"
  image="/my-image.png"
>
  <!-- Page content -->
</DefaultLayout>

Available SEO Props

Prop	Type	Description
title	string	Page title
description	string	Page description
url	string	Canonical URL (defaults to current URL)
image	ImageMetadata | string	Social sharing image
author	string	Page author
type	'website' | 'article'	Open Graph type
useTitleTemplate	boolean	Whether to append site name (default: true)

Default values for these props are pulled from your theme.config.ts SEO settings.

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.