Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
376 lines (274 loc) · 10.2 KB

CONTRIBUTING.md

File metadata and controls

376 lines (274 loc) · 10.2 KB
Raw

Contributing to APG Patterns Examples

Thank you for your interest in contributing to APG Patterns Examples! This document provides guidelines and instructions for contributing to this project.

Table of Contents

Code of Conduct

This project adheres to a Code of Conduct. By participating, you are expected to uphold this code. Please read CODE_OF_CONDUCT.md before contributing.

Getting Started

Prerequisites

  • Node.js 20 or higher
  • npm (comes with Node.js)
  • Git
  • Basic understanding of:
    • WAI-ARIA and accessibility principles
    • At least one of: React, Vue, Svelte, or Astro
    • TypeScript
    • Tailwind CSS

Useful Resources

Development Setup

  1. Fork the repository on GitHub

  2. Clone your fork:

    git clone https://github.com/YOUR_USERNAME/apg-patterns-examples.git
cd apg-patterns-examples

  3. Add upstream remote:

    git remote add upstream https://github.com/masuP9/apg-patterns-examples.git

  4. Install dependencies:

    npm install

  5. Start development server:

    npm run dev
# The port is derived from the worktree path (Astro prints the exact URL),
# and the site is served under the base path, e.g.
#   http://localhost:<port>/apg-patterns-examples/

Development Workflow

Creating a Feature Branch

# Update your local main branch
git checkout main
git pull upstream main

# Create a feature branch
git checkout -b feature/your-feature-name

Branch Naming Convention

  • feature/pattern-name - New pattern implementation
  • fix/issue-description - Bug fixes
  • docs/description - Documentation updates
  • refactor/description - Code refactoring
  • test/description - Test additions or modifications

Making Changes

  1. Make your changes in the feature branch
  2. Test your changes thoroughly
  3. Run linting and formatting: 
    npm run lint     # Runs all checks in parallel (ESLint, TypeScript, Astro)
npm run format
    For faster iteration, you can run individual checks: 
    npm run lint:eslint  # ESLint only
npm run lint:types   # TypeScript type check only
npm run lint:astro   # Astro check only
  4. Ensure all tests pass: 
    npm run test

Keeping Your Branch Updated

git fetch upstream
git rebase upstream/main

Coding Standards

General Rules

  • Follow the Coding Rules document
  • Use TypeScript with strict type checking
  • Minimize use of type assertions (as)
  • Prefer type guards and proper type definitions
  • Write self-documenting code with clear variable names
  • Add comments only where logic isn't self-evident

Code Formatting

We use Prettier for most files and @takazudo/mdx-formatter for MDX files (.prettierignore excludes *.mdx). Both run in parallel via npm-run-all2:

# Format all files (Prettier + mdx-formatter in parallel)
npm run format

# Check formatting
npm run format:check

# MDX only
npm run format:mdx
npm run format:mdx:check

Formatting Rules:

  • Semicolons: Required
  • Quotes: Single quotes (double in JSX attributes)
  • Indentation: 2 spaces
  • Trailing commas: ES5
  • Line width: 100 characters
  • Tailwind CSS class ordering: Automatic

TypeScript Guidelines

See CODING_RULES.md for detailed TypeScript requirements, especially:

  • Type assertion restrictions
  • Type guard patterns
  • DOM API handling
  • Safe access helpers

Component Guidelines

Accessibility Requirements

All components MUST:

  1. Follow APG Patterns: Implement the exact ARIA roles, states, and properties specified in WAI-ARIA APG
  2. Keyboard Navigation: Support all required keyboard interactions
  3. Screen Reader Support: Provide appropriate labels and announcements
  4. Focus Management: Handle focus correctly (visible indicators, logical order)
  5. High Contrast Mode: Work correctly in Windows High Contrast Mode
  6. Reduced Motion: Respect prefers-reduced-motion preference

Framework Parity

When implementing a pattern, ensure:

  • All four frameworks (React, Vue, Svelte, Astro) have the same functionality
  • Component APIs are consistent across frameworks
  • All implementations pass the same accessibility tests
  • Documentation is complete for each framework

Component Structure

Each pattern should include:

src/patterns/{pattern}/
├── meta.ts                          # Pattern metadata (single source of truth)
├── DemoSection.react.astro          # React demo
├── DemoSection.vue.astro            # Vue demo
├── DemoSection.svelte.astro         # Svelte demo
├── DemoSection.web-component.astro  # Astro Web Component demo
├── {pattern}-demo-data.ts           # Shared demo data (optional)
├── TestingDocs.astro                # Test documentation
├── {Pattern}.tsx              # React implementation
├── {Pattern}.vue              # Vue implementation
├── {Pattern}.svelte           # Svelte implementation
├── {Pattern}.astro            # Astro/Web Components implementation
├── {Pattern}.test.tsx         # React tests
├── {Pattern}.test.vue.ts      # Vue tests
├── {Pattern}.test.svelte.ts   # Svelte tests
└── {pattern}.md               # AI assistant reference (llm.md)

src/content/accessibility-docs/{pattern}/
├── en.mdx                     # Accessibility docs (English)
└── ja.mdx                     # Accessibility docs (Japanese)

Required Documentation

  1. Accessibility docs (src/content/accessibility-docs/{pattern}/en.mdx, ja.mdx): Include sections for:

    • Native HTML Considerations (if applicable)
    • WAI-ARIA Roles
    • WAI-ARIA States/Properties
    • Keyboard Support

  2. meta.ts: Pattern metadata including title, description, TOC, resources, and per-framework API docs (see src/lib/pattern-meta-types.ts for the PatternMeta type)

  3. llm.md: AI-friendly reference (see .internal/llm-md-template.md)

Testing

Running Tests

# Run all tests
npm run test

# Run tests in watch mode
npm run test:ui

# Run tests with coverage
npm run test:coverage

# Run tests for CI
npm run test:ci

Testing Requirements

All components must have tests for:

  1. ARIA Compliance:

    • Correct roles
    • Required states and properties
    • Dynamic state updates

  2. Keyboard Navigation:

    • All required key handlers
    • Focus management
    • Tab order

  3. User Interactions:

    • Click/tap events
    • State changes
    • Event callbacks

  4. Accessibility:

    • jest-axe automated checks
    • Screen reader announcements (where applicable)

See the Testing Strategy page for detailed testing guidelines (source: src/testing-strategy/content.mdx).

Pull Request Process

Before Submitting

  1. ✅ All tests pass (npm run test)
  2. ✅ Linting passes (npm run lint)
  3. ✅ Code is formatted (npm run format)
  4. ✅ Documentation is updated
  5. ✅ Commits follow our commit message guidelines

Submitting a PR

  1. Push your branch to your fork:

    git push origin feature/your-feature-name

  2. Create a Pull Request on GitHub

  3. Fill out the PR template with:

    • Description of changes
    • Related issue number (if applicable)
    • Screenshots/GIFs (for UI changes)
    • Testing checklist

  4. Wait for review: A maintainer will review your PR and may request changes

  5. Address feedback: Make requested changes and push updates

  6. Merge: Once approved, a maintainer will merge your PR

PR Review Criteria

PRs will be reviewed for:

  • ✅ APG compliance and accessibility
  • ✅ Code quality and adherence to standards
  • ✅ Test coverage
  • ✅ Documentation completeness
  • ✅ Framework parity (all 4 frameworks work identically)
  • ✅ No breaking changes (unless discussed)

Commit Message Guidelines

We follow Conventional Commits:

Format

<type>(<scope>): <subject>

<body>

<footer>

Types

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation only
  • style: Code style changes (formatting, no logic change)
  • refactor: Code refactoring
  • test: Adding or updating tests
  • chore: Maintenance tasks

Examples

feat(accordion): implement accordion pattern for all frameworks

- Add React, Vue, Svelte, and Astro implementations
- Include keyboard navigation (Arrow keys, Home, End)
- Add comprehensive accessibility tests
- Document ARIA roles and properties

Closes #42

fix(tabs): correct focus management on tab deletion

When a selected tab is deleted, focus now moves to the
adjacent tab instead of losing focus.

Fixes #128

docs(contributing): add component guidelines section

Scope

Use the pattern name or area of change:

  • accordion, tabs, dialog, etc. - For pattern-specific changes
  • ci - CI/CD changes
  • deps - Dependency updates
  • a11y - Cross-cutting accessibility improvements

Questions?

  • General questions: Open a Discussion
  • Bug reports: Open an Issue
  • Feature requests: Open an Issue with the enhancement label

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to make the web more accessible! 🎉