A11yhood Front End Website

This is the main repository for the A11yhood front end website. A11yhood is a community platform for discovering, reviewing, and discussing open-source assistive technologies. A11yhood serves as a central hub for disabled and non-disabled makers, developers, and contributors to find, use, and contribute to accessibility projects.

To join our community and learn about contributing, go to the community repository. Learn more

Tech Stack

Frontend

• Framework: React 19 with TypeScript
• Build Tool: Vite
• Routing: React Router DOM v7
• Styling: Tailwind CSS v4
• UI Components: shadcn/ui, Radix UI
• Icons: Phosphor Icons, FontAwesome
• Forms: React Hook Form with Zod validation
• Testing: Vitest, React Testing Library
• Auth: Supabase Auth
• State Management: React Context, TanStack Query

Project Structure

├── src/
│   ├── components/          # React components
│   │   ├── ui/             # shadcn/ui components
│   │   ├── AboutPage.tsx   # About page
│   │   ├── AdminDashboard.tsx
│   │   ├── BlogManager.tsx
│   │   ├── CollectionsList.tsx
│   │   ├── ProductDetail.tsx
│   │   └── ...             # Other feature components
│   ├── contexts/           # React contexts
│   │   └── AuthContext.tsx
│   ├── hooks/              # Custom hooks
│   ├── lib/                # Utilities and services
│   │   ├── supabase.ts     # Supabase client
│   │   ├── api.ts          # API client
│   │   ├── scrapers.ts     # Web scraping utilities
│   │   ├── types.ts        # TypeScript type definitions
│   │   └── utils.ts        # Helper functions
│   ├── styles/             # Global styles
│   ├── __tests__/          # Test files
│   │   ├── components/
│   │   ├── accessibility/
│   │   ├── integration/
│   │   └── security/
│   └── App.tsx             # Main application
└── public/                 # Static assets

Getting Started

Prerequisites

• pixi

Install Pixi (macOS)

Visit https://pixi.prefix.dev for more information.

Choose one option:

# Homebrew
brew install pixi

# Official installer
# Works for Linux/Mac only 
curl -fsSL https://pixi.sh/install.sh | bash

Verify installation:

pixi --version

Using Pixi

Use Pixi to provide the project runtime, then run npm commands inside that environment.

Installation

We assume throughout that you are already running pixi.

 pixi shell

1. Clone the repository

   git clone https://github.com/a11yhood/a11yhood.github.io.git
   cd a11yhood.github.io

2. Install Node + npm dependencies via Pixi

   pixi shell
   npm install

3. Set up environment variables

   Minimal .env.local for local development:

   VITE_DEV_MODE=true
   VITE_DEV_USER=admin

   Production auth flows require Supabase values:

   VITE_SUPABASE_URL=your_supabase_url
   VITE_SUPABASE_ANON_KEY=your_supabase_anon_key

   See env.example and env.example.test for full configuration options.

4. Start the development server

   npm run dev

   The application will be available at http://localhost:5173

Running Tests

pixi shell

# Run tests in watch mode
npm test

# Run tests once
npm run test:run

# Run tests with coverage
npm run test:coverage

# Run tests with UI
npm run test:ui

# Lint
npm run lint

# Accessibility
npm run test:a11y
npm run test:a11y-integration

Notes:

• Unit tests can run without Supabase variables.
• Integration tests require a running backend and valid dev auth mode (VITE_DEV_MODE=true).

Building for Production

# Build the application
npm run build

# Preview the production build
npm run preview

Bundle-only Vite build via Pixi task

Note: this skips tests and TypeScript type checking

pixi run build-vite

# Production preview
npm run preview

Code Quality

The project includes:

• ESLint for code linting
• TypeScript for type safety
• Vitest for unit and integration testing
• React Testing Library for component testing
• Accessibility tests for critical UI components

Key Features Explained

URL Routing

Each page has a unique, shareable REST-style URL:

• Product detail: /product/{productId}
• Collection: /collection/{collectionId}
• Blog post: /blog/{slug}
• User profile: /profile
• Public profile: /profile/{username}
• Admin dashboard: /admin

Product Sources

Products are automatically scraped from:

• GitHub: Projects tagged with accessibility keywords
• Ravelry: Patterns tagged as accessibility
• Thingiverse: 3D printable assistive devices

Products gathered through such scraping receive an initial review that is based on their stars on their respective platforms. For ravelry, this is simply its rating out of 5 from Ravelry. For Github and Thingiverse, however, there is no such analagous metric. For these, the initial rating is a mapping based on the number of users who have starred the product on the source site. This initial score mapping is exponential and the highest scores (e.g. 5.0) map to 100,000 or more stars on Github, and 1,000 or more stars on Thingiverse (a scale representative of extreme popularity on each respective site). Thus, many products start with ratings that appear low: this is meant to estimate overall community interest rather than act as an indictment on a product's usefulness or quality. Users' ratings of products on the a11yhood site will update this overall rating.

User Roles

• Public: Browse and search products
• Authenticated: Create collections, review products, submit content
• Admin: Moderate content, manage users, view analytics

Deployment

The site is hosted on GitHub Pages. Production deploys are gated behind a version tag — merging to main alone does not deploy:

PR preview publishing is currently disabled. Pull requests still run lint, tests, and accessibility checks in CI.

See GITHUB_PAGES_DEPLOYMENT.md for the full release process, PR preview details, and required repository settings.

Full Backend Test Validation

The full backend-capable suite is intentionally manual-triggered:

• Internal PRs: add label run-full-backend to trigger .github/workflows/backend-tests.yml.
• Fork PRs: maintainers can comment /run-full-backend; .github/workflows/full-backend-from-comment.yml dispatches the full suite on the PR merge ref.

This pattern avoids exposing repository secrets to untrusted fork events while preserving pre-merge backend validation.

Copilot Accessibility Setup

This repository uses both custom instructions and custom agents for accessibility-focused development.

Always-on instructions

• Repository-wide instructions: .github/copilot-instructions.md
• Markdown-specific instructions: .github/instructions/markdown-accessibility.instructions.md

Custom agents

• Markdown accessibility assistant: .github/agents/markdown-a11y-assistant.agent.md
• Accessibility review advisor: .github/agents/a11y-review-advisor.agent.md

GitHub-hosted agent setup

• Setup workflow for GitHub agent runs: .github/workflows/copilot-setup-steps.yml

Use this setup when you want Copilot to apply repo accessibility standards consistently and delegate focused accessibility tasks to specialized agents.

Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

For contribution norms, review expectations, and release conventions across A11yhood, see the community guide: Community CONTRIBUTING.md.

When opening a pull request in this repository, complete the accessibility checklist in .github/PULL_REQUEST_TEMPLATE.md.

Partners and Funders

Developed with support from:

• The Tides Foundation
• National Institute on Disability, Independent Living, and Rehabilitation Research (NIDILRR)
• Center for Research and Education on Accessible Technology and Experiences (CREATE)

In collaboration with:

• GitHub
• Grassroots Open Assistive Technology (GOAT)
• Center for Accessibility and Open Source (CAOS)

License

BSD 3-Clause License - See LICENSE file for details.

Links

• Website: a11yhood.org
• Repository: github.com/a11yhood/a11yhood.github.io
• Issues: github.com/a11yhood/a11yhood.github.io/issues

---

A11yhood is an open resource for everyone interested in accessible technology. Join us in making assistive technology more discoverable and accessible!