DOCSEARCHbyAlgolia
Submit Docs

Accessible Astro Starter

repository·main·Indexed 22 days ago

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

An accessibility-first Astro starter template (v5.2.5) designed for WCAG 2.2 AA and EAA compliance. Built with Astro 6.1.1+, Tailwind CSS 4.1+, and TypeScript, it includes semantic components, a keyboard-driven command launcher, and strict accessibility linting via eslint-plugin-jsx-a11y. The package provides a CLI (`create-accessible-astro-starter`) to scaffold projects with presets such as full, blog, portfolio, minimal, and barebones.

Tokens
8.1K
Snippets
31
Records
37
Agent score
78%

What's inside accessible-astro-starter

  1. Overview of Accessible Astro Starter features

    main

    Accessible Astro Starter is an SEO and accessibility-focused Astro template designed for WCAG 2.2 AA and EAA compliance.

    Core Technical Stack:

    • Astro 6.1.1+
    • Tailwind CSS 4.1+ with OKLCH color system and automatic palette generation.
    • TypeScript with path aliases and content collections support.
    • Linting & Formatting: Prettier (prettier-plugin-astro, prettier-plugin-tailwind) and ESLint with strict accessibility settings (eslint-plugin-jsx-a11y).
    • Typography: Atkinson Hyperlegible font for improved readability.
    • Icons: Lucide icon set via astro-icon.

    Key Accessibility Features:

    • Semantic Components: Button, Link, and Heading components for proper HTML structure.
    • Navigation: SkipLinks.astro for skipping to main content, and Navigation.astro with keyboard-accessible dropdowns.
    • User Preferences: Built-in support for Dark Mode, High Contrast, and Reduced Motion (via prefers-reduced-motion).
    • Command Launcher: A keyboard-driven navigation tool (Cmd/Ctrl+K) for quick access to site features.
    • Form Accessibility: Enhanced form components (Form, Input, Textarea, Checkbox, Radio, Fieldset) with automatic validation and screen reader support.
    • Visual Aids: .sr-only utility class for screen-reader-only text and an outline focus indicator that works on all backgrounds.

  2. Get started with a cloned repository

    main

    If you have cloned the repository locally, use the following commands to set up your development environment and build your site:

    • npm install: Installs all necessary dependencies.
    • npm run dev: Starts the local development server at http://localhost:4321.
    • npm run build: Compiles your production site into the ./dist/ directory.
    • npm run preview: Serves your local production build for testing before deployment.
    npm install
npm run dev
npm run build
npm run preview

  3. Scaffold a new project with the CLI

    main

    Use the create-accessible-astro-starter CLI to quickly generate a new project based on this starter. The CLI is interactive and will prompt you for:

    • The project directory name
    • Your site name
    • A preset selection: full, blog, portfolio, minimal, or barebones
    • Whether to include the Accessible Astro launcher

    Generated projects are optimized for end-users, meaning they strip out contributor-only workspace tooling (like scripts/workspace-config.js) and provide a simplified astro.config.mjs.

    npm create accessible-astro-starter@latest

  4. Customize the Accessibility Statement template

    main

    The accessibility-statement.mdx file is a template following the W3C WAI Accessibility Statement structure. To make this statement valid for your own project, you must replace all placeholder text marked with [brackets] with your organization's specific details.

    Required updates include:

    • [Organization Name]: Your company or project name.
    • [website/product name]: The name of your site or application.
    • [link to a11y issues]: A URL to your issue tracker (e.g., GitHub issues) filtered for accessibility work.
    • [email]: A contact email for accessibility feedback.
    • [link to new issue]: A direct link to create a new issue.
    • [Other channel]: Any additional feedback methods (e.g., Discord, Slack).
    • [X]: The number of business days you aim to respond to feedback.
    • [date]: The creation and last updated dates.

  6. Test the CLI locally

    main

    If you are working within the starter repository and want to test the CLI behavior without publishing, you can use the create:local script.

    Pass the desired output directory as the first positional argument. Note that subsequent prompts (like the site name) will only affect the metadata of the generated project, not the directory structure.

    npm run create:local -- my-demo-site

  7. Define project metadata in MDX frontmatter

    main

    Each project MDX file should begin with a YAML frontmatter block to define its metadata. This metadata is used for rendering project lists, descriptions, and categorization.

    Required/Recommended keys:

    • title: The name of the project.
    • author: The creator of the project.
    • description: A brief summary of the project.
    • tags: An array of strings used for categorization (e.g., ['Accessibility', 'Smart-Home']).
    ---
title: Voice-First Smart Home Assistant
author: John Doe
description: A comprehensive smart home solution designed specifically for users with visual impairments, featuring voice-first interactions and haptic feedback
tags: ['Accessibility', 'Smart-Home', 'IoT']
---

  8. Set up local development for the CLI package

    main

    To set up a local development environment for the create-accessible-astro-starter package from the starter repository root, follow these steps:

    1. Install dependencies: npm install
    2. Build the CLI: npm run build:cli
    3. Run CLI tests: npm run test:cli

    If you are working directly inside the package directory, use npm run build and npm run test for package-local checks.

    npm install
npm run build:cli
npm run test:cli

  9. Use MDX to include components in Markdown

    main

    This project supports Astro's MDX feature, allowing you to import and use interactive components directly within your .mdx files. You can also leverage built-in syntax highlighting via Shiki for code blocks.

    To use components in an MDX page:

    1. Define the page layout in the frontmatter using layout: ../layouts/MarkdownLayout.astro (or your preferred layout).
    2. Import components (e.g., from astro-icon or accessible-astro-components) in the MDX frontmatter or body.
    3. Use the components within the Markdown content using JSX-like syntax.
    ---
layout: ../layouts/MarkdownLayout.astro
title: MDX Page
---

import { Icon } from 'astro-icon/components'
import { Notification } from 'accessible-astro-components'

# MDX Page

<Notification type="info">
  <Icon aria-hidden="true" name="lucide:info" />
  <p>
    <strong>Info:</strong> This page utilizes Astro's MDX feature...
  </p>
</Notification>

```js
console.log('Hello Accessible World!')

  10. Create a Markdown page using MarkdownLayout

    main

    To create a new content page in this project, create a .md file in the src/pages/ directory. You must include a frontmatter block that specifies the layout property to ensure the content is wrapped in the appropriate accessible structure. Use ../layouts/MarkdownLayout.astro as the layout path for standard markdown content.

    ---
layout: ../layouts/MarkdownLayout.astro
title: Markdown Page
---

# Markdown Page

Your content goes here...

  11. Use the Astro Image component for project galleries

    main

    When building project galleries, use the standard Image component from astro:assets. To ensure a consistent grid layout, provide src, alt, width, and height props, and apply CSS classes for sizing and rounding.

    import { Image } from 'astro:assets'

<Image
  src="/projects/project-image-1.png"
  alt="Accessible Learning Hub student dashboard with personalized content"
  width={1200}
  height={600}
  class="h-[250px] w-full rounded-lg object-cover"
/>

  12. Use project gallery components in MDX

    main

    When creating project documentation or case studies in .mdx files, you can use the following components to display media and testimonials:

    • BreakoutImage: Used for large, impactful images. Setting decorative={true} indicates the image is for visual flair and does not require alt text for screen readers.
    • Image (from astro:assets): The standard way to render optimized images. Always provide src, alt, width, and height for accessibility and performance.
    • BlockQuote: Used to display testimonials. It accepts an author prop to attribute the quote.

    Example usage in an MDX file:

    import BlockQuote from '@components/BlockQuote.astro'
import BreakoutImage from '@components/BreakoutImage.astro'
import { Image } from 'astro:assets'

<BreakoutImage src="/projects/project-image-1.png" decorative={true} />

<Image
  src="/projects/project-image-1.png"
  alt="Description of image"
  width={1200}
  height={600}
/>

<BlockQuote author="Name">
  Quote text goes here.
</BlockQuote>
    import BlockQuote from '@components/BlockQuote.astro'
import BreakoutImage from '@components/BreakoutImage.astro'
import { Image } from 'astro:assets'

<BreakoutImage src="/projects/project-image-1.png" decorative={true} />

<Image
  src="/projects/project-image-1.png"
  alt="Smart home assistant interface showing voice command visualization"
  width={1200}
  height={600}
  class="h-[250px] w-full rounded-lg object-cover"
/>

<BlockQuote author="Maria Rodriguez, Beta Tester">
  This system has given me back my independence at home.
</BlockQuote>