Skip to content
Accessible Astro Documentation

Development setup

Development environment

Before you start contributing, make sure you have all the necessary tools and software installed. This will help you get up and running quickly and ensure a smooth development experience.

  1. Prerequisites

    • Node.js 18.14.1 or higher
    • npm (or pnpm/Yarn)
    • Git or GitHub Desktop for example
    • A code editor (we recommend VS Code or Cursor)
    • Browser developer tools
    • Screen reader for testing

  2. Recommended VS Code extensions

    • Astro
    • ESLint
    • Prettier
    • TypeScript
    • MDX

Project structures

Understanding the project structure is crucial for effective development. Below you’ll find the structure for both our component library and themes, which follow Astro’s recommended practices while maintaining a clear separation of concerns.

Components

  • Directoryaccessible-astro-components/
    • Accordion.astro
    • AccordionItem.astro
    • Breadcrumbs.astro
    • Card.astro
    • DarkMode.astro
    • Media.astro
    • Modal.astro
    • Notification.astro
    • Pagination.astro
    • SkipLinks.astro
    • Tabs.astro
    • Video.astro
    • Directorytypes
      • index.d.ts
    • package.json
    • tsconfig.json

Themes

Accessible Astro Starter

  • 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

Accessible Astro Dashboard

  • Directorypublic/
    • … // Other assets
  • Directorysrc/
    • Directoryassets/
      • Directoryimg/ // Contains the logo
        • …
      • Directoryscss/
        • Directorybase/ // Core styles and utilities
          • …
    • Directorycomponents/
      • DashboardWidget.astro
      • EmptyState.astro
      • LoginForm.astro
      • Navigation.astro
      • ResponsiveToggle.astro
    • Directorylayouts/
      • DefaultLayout.astro // Default page layout
      • LoginLayout.astro // Login page layout
    • Directorypages/
      • 404.astro
      • index.astro
      • login.astro // Login page
      • media.astro
      • messages.astro
      • products.astro
      • settings.astro
      • users.astro
  • package.json
  • astro.config.mjs

Development workflow

Follow these steps to set up your development environment and start contributing. Whether you’re working on components, themes, or documentation, this workflow will help you stay organized and efficient.

  1. Setup your repository

    Terminal window
    # Clone the repository
    git clone https://github.com/YOUR-USERNAME/REPO-NAME.git
    cd REPO-NAME
    

    # Install dependencies
    npm install
    

    # Start development server
    npm run dev

  2. Make your changes

    • Follow the style guide
    • Write meaningful commit messages
    • Add tests where applicable
    • Update documentation

  3. Test your changes

    Terminal window
    # Components
    npm run typecheck  # Check TypeScript
    npm run build      # Test production build
    

    # Themes
    npm run build      # Test production build
    npm run preview    # Test built site

  4. Submit your changes

    Terminal window
    git add .
    git commit -m "type: description"
    git push origin branch-name

Coding standards

We maintain high standards for our code to ensure accessibility, maintainability, and consistency across all projects. These guidelines help us create robust and user-friendly components and themes.

TypeScript

  • Use TypeScript for all new code
  • Include proper type definitions
  • Document props with JSDoc comments
  • Avoid any types

Accessibility

  • Follow WAI-ARIA guidelines
  • Include proper ARIA attributes
  • Support keyboard navigation
  • Test with screen readers
  • Consider color contrast
  • Support reduced motion

CSS

  • Use logical properties (inline/block)
  • Follow mobile-first approach
  • Support dark mode with light-dark()
  • Use consistent border-radius (0.5rem)
  • Use HSL colors
  • Support prefers-reduced-motion
  • Use :where() for lower specificity

Testing

Quality assurance is a crucial part of our development process. We focus on manual testing and accessibility validation to ensure our components and themes work well for everyone.

Components

  • Manual accessibility testing
  • TypeScript validation
  • Browser testing
  • Screen reader testing
  • Keyboard navigation testing
  • Reduced motion testing

Themes

  • Cross-browser testing
  • Responsive testing
  • Performance testing
  • Accessibility validation
  • Dark mode testing
  • Screen reader testing
  • Keyboard navigation testing

Common issues

During development, you might encounter some common issues. Here are some solutions that can help you resolve them quickly and get back to coding.

Build errors

Terminal window
# Clear cache and node_modules
npm run clean
rm -rf node_modules
npm install

Type errors

  • Check prop types
  • Update type definitions
  • Run typecheck command

Resources

These resources will help you better understand our technical stack and accessibility requirements. We recommend bookmarking them for future reference.