feat: Added Accessibility section to the Development and CONTRIBUTING guides (#517)

Author: davidverdu

CONTRIBUTING.md

@@ -56,6 +56,29 @@ Before submitting code changes:
    ```bash
    make test
     ```
+
+## ♿ Accessibility
+Accessibility is a core consideration for this project. While OnDemand Loop is not fully compliant with accessibility standards (such as WCAG 2.1 or Section 508), we strive for **incremental improvements** with every change.
+
+When contributing, please:
+
+- **Review the [Accessibility Guidelines](https://iqss.github.io/ondemand-loop/development_guide/accessibility.md)** before submitting UI changes.
+- **Follow best practices**:
+    - Use semantic HTML elements and landmarks.
+    - Ensure all functionality is available via keyboard.
+    - Provide descriptive labels for form inputs and interactive elements.
+    - Maintain sufficient color contrast.
+    - Apply ARIA attributes only when necessary and correctly.
+- **Run accessibility checks** using tools such as:
+    - [axe DevTools](https://www.deque.com/axe/devtools/)
+    - [Lighthouse](https://developers.google.com/web/tools/lighthouse)
+    - [WAVE](https://wave.webaim.org/)
+- **Call out accessibility considerations in your PR description**:
+    - Mention improvements you made (e.g., added keyboard support, improved labels).
+    - Flag any known limitations so reviewers can double-check.
+
+Even small contributions to accessibility make a meaningful difference. Please treat every change as an opportunity to improve inclusivity and avoid regressions.
+
 ## ✅ Pull Requests
 After completing your changes, open a Pull Request (PR):
 - Link it to the relevant issue.

docs/guide/content/development_guide/accessibility.md

@@ -0,0 +1,62 @@
+# Accessibility Guidelines
+
+### Why Accessibility Matters
+Accessibility ensures that people of all abilities can use OnDemand Loop effectively.
+Accessible features often improve the overall usability of the product, reduce friction for everyone, and demonstrate respect for our diverse user base.  
+Building with accessibility in mind also reduces long-term maintenance costs by avoiding retrofits.
+
+### Current State of Accessibility
+We have implemented several accessibility-conscious practices across the application, such as:
+
+- Using semantic HTML where possible
+- Applying ARIA labels to clarify the purpose of interactive components for assistive technologies
+- Providing keyboard navigation for primary workflows so users are not blocked by pointer-only interactions
+- Improving color contrast between text and backgrounds in core UI areas
+
+These measures improve the experience, but the application is **not fully compliant with accessibility standards** (e.g., WCAG, Section 508).
+While we strive to follow best practices, the current state should not be interpreted as certification or full accessibility compliance.
+
+### Developer Responsibility
+Every change to the application is an opportunity to improve accessibility. When developing new features or modifying existing ones, you should:
+
+- Favor semantic HTML elements and landmarks to convey structure and meaning (avoid relying only on `<div>` and `<span>`)
+- Ensure all interactive elements (buttons, links, inputs) are accessible via keyboard
+- Provide clear and descriptive labels for inputs and form controls (visible label, `aria-label`, or equivalent association)
+- Check that color contrast meets at least minimum accessibility requirements
+- Apply ARIA attributes only where necessary and ensure they remain in sync with component state
+- Test new functionality with keyboard navigation and screen reader tools when possible
+
+### Limitations
+At this stage, the application does not guarantee compliance with any accessibility standard.
+
+Our goal is **incremental improvement**—making the application more accessible over time without giving a false impression of full accessibility.
+
+### Quick Checklist for Developers
+Before submitting your changes, review the following:
+
+- [ ] Did I use semantic HTML tags and landmarks appropriately?
+- [ ] Can I navigate my feature entirely with a keyboard?
+- [ ] Do all inputs and interactive elements have clear, accessible labels or names?
+- [ ] Is the color contrast sufficient for text and essential UI elements?
+- [ ] Did I avoid unnecessary or incorrect ARIA attributes, and keep them in sync with UI state?
+- [ ] Did I test the main user paths with keyboard navigation or assistive tools?
+
+
+---
+
+By keeping accessibility in mind with every change, we ensure steady progress toward a more inclusive application. Even small improvements add up over time.
+
+!!! info "Testing Tools and Resources"
+
+    **Accessibility Testing Tools:**
+
+    - [WAVE Web Accessibility Evaluation Tool](https://wave.webaim.org/) — Browser extension for identifying accessibility issues
+    - [axe DevTools](https://www.deque.com/axe/devtools/) — Browser extension for automated accessibility testing
+    - [Lighthouse Accessibility Audit](https://developers.google.com/web/tools/lighthouse) — Built into Chrome DevTools
+    - [NVDA Screen Reader](https://www.nvaccess.org/) — Free screen reader for testing (Windows)
+    - [VoiceOver](https://www.apple.com/accessibility/vision/) — Built-in screen reader for macOS
+
+    **Standards Reference:**
+
+    - [WCAG 2.1 Guidelines](https://www.w3.org/TR/WCAG21/) — Web Content Accessibility Guidelines (A and AA levels)
+    - [WebAIM Resources](https://webaim.org/) — Practical accessibility guidance and tutorials

docs/guide/content/development_guide/e2e_tests.md

@@ -2,15 +2,15 @@
 
 OnDemand Loop uses [Cypress](https://cypress.io) for end-to-end (E2E) automated testing. These tests verify that the application works correctly from a user's perspective by simulating real interactions with the browser interface.
 
-## Overview
+### Overview
 
 The automated tests are located in the `e2e_tests/` directory and provide:
 
 - **End-to-end testing** of critical user workflows
 - **Docker-based execution** for consistency across development and CI/CD environments
 - **GitHub Actions integration** for automated testing on code changes
 
-### Test Structure
+#### Test Structure
 
 ```
 e2e_tests/
@@ -26,15 +26,15 @@ e2e_tests/
 └── docker-compose.yml         # Test environment setup
 ```
 
-## Running Tests Locally
+### Running Tests Locally
 
-### Prerequisites
+#### Prerequisites
 
 - Docker and Docker Compose installed
 - Make utility
 - Access to test credentials (see [Local Environment](local_environment.md))
 
-### Quick Start
+#### Quick Start
 
 1. **Start the test environment:**
 
@@ -64,7 +64,7 @@ make cypress_run
 make clean
 ```
 
-### Available Make Targets
+#### Available Make Targets
 
 | Target | Description |
 |--------|-------------|
@@ -77,7 +77,7 @@ make clean
 | `cypress_run` | Run Cypress tests headless |
 | `clean` | Stop environment and clean up artifacts |
 
-### Environment Variables
+#### Environment Variables
 
 Configure tests using these environment variables:
 
@@ -93,9 +93,9 @@ Example:
 CYPRESS_SPEC=cypress/e2e/homepage.cy.js make cypress_run
 ```
 
-## Writing Tests
+### Writing Tests
 
-### Test Structure
+#### Test Structure
 
 Follow this pattern for new tests:
 
@@ -116,7 +116,7 @@ describe('Feature Name', () => {
 })
 ```
 
-### Best Practices
+#### Best Practices
 
 1. **Use data attributes** for element selection:  
    ```html
@@ -147,21 +147,21 @@ describe('Feature Name', () => {
    })
    ```
 
-## Adding New Tests
+#### Adding New Tests
 
 1. **Create test files** in `cypress/e2e/` with the `.cy.js` extension
 2. **Follow naming conventions**: `feature-name.cy.js`
 3. **Import/create required utilities**
 
-## CI/CD Integration
+#### CI/CD Integration
 
 Tests run automatically in GitHub Actions on:
 
 - **Push to main branch** with changes to `application/` or `e2e_tests/`
 - **Pull requests** targeting main branch with changes to `application/` or `e2e_tests/`
 - **Manual workflow dispatch**
 
-### GitHub Actions Workflow
+#### GitHub Actions Workflow
 
 The workflow (`.github/workflows/e2e-tests.yml`) performs:
 
@@ -172,16 +172,16 @@ The workflow (`.github/workflows/e2e-tests.yml`) performs:
 5. **Run tests** with `make cypress_run`
 6. **Upload artifacts** (results, screenshots) on failure
 
-### Test Artifacts
+#### Test Artifacts
 
 When tests fail, the following artifacts are automatically uploaded:
 
 - **Screenshots** from failed tests
 - **Test results** in JUnit XML format
 
-## Troubleshooting
+### Troubleshooting
 
-### Debugging Tests
+#### Debugging Tests
 
 1. **View environment logs:**
    ```bash

docs/guide/content/development_guide/index.md

@@ -43,6 +43,9 @@ The documentation is organized by topic to help you find what you need quickly:
 - [Contributing a Change](contributing.md)  
   Best practices and workflow for contributing code or documentation.
 
+- [Accessibility Guidelines](accessibility.md)  
+  Practices taken into account to make the application accessible.
+
 - [Testing](testing.md)  
   How the Rails test suite is structured and executed using the provided Make targets.
 

docs/guide/mkdocs.yml

@@ -46,6 +46,7 @@ nav:
       - Open OnDemand: development_guide/ood.md
       - Dataverse Integration: development_guide/dataverse_integration.md
       - Contributing a Change: development_guide/contributing.md
+      - Accessibility Guidelines: development_guide/accessibility.md
       - Testing: development_guide/testing.md
       - Manual Testing: development_guide/manual_testing.md
       - E2E Tests: development_guide/e2e_tests.md
@@ -59,6 +60,8 @@ markdown_extensions:
   - admonition
   - footnotes
   - tables
+  - pymdownx.tasklist:
+      custom_checkbox: true
   - pymdownx.highlight:
       anchor_linenums: true
       linenums: false