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.

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
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.

Setup your repository

# 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

Make your changes
- Follow the style guide
- Write meaningful commit messages
- Add tests where applicable
- Update documentation

Test your changes

# 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

Submit your changes

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

# 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.