```
#### Decorative Images
Images that are purely decorative:
```html
```
> [!NOTE]
> Use `alt=""` for decorative images. This tells screen readers to skip the image.
#### Functional Images
Images used as links or buttons:
```html
```
#### Complex Images
Charts, graphs, and diagrams:
```html
Detailed description: Sales increased from $100K in Q3 to $130K in Q4...
``` #### Text in Images Avoid text in images, but if necessary: ```html
```
## Best Practices
### 1. Fix Issues Early
Run checks frequently during development:
```bash
# Add to your development workflow
python manage.py check && python manage.py runserver
```
### 2. Use Pre-commit Hooks
Prevent commits with accessibility issues:
```bash
# .git/hooks/pre-commit
#!/bin/bash
python manage.py check
```
### 3. Integrate with CI/CD
Add to your CI pipeline:
```yaml
# .github/workflows/ci.yml
- name: Accessibility Checks
run: python manage.py check --deploy --fail-level WARNING
```
### 4. Document Exceptions
If you need to silence a check, document why:
```python
# settings.py
SILENCED_SYSTEM_CHECKS = [
'accessible_django.W001', # Silenced because: [reason]
]
```
> [!WARNING]
> Only silence checks when absolutely necessary. Document the reason clearly.
### 5. Team Education
Ensure your team understands accessibility:
- Share this documentation
- Conduct accessibility training
- Review accessibility in code reviews
## Advanced Usage
### Custom Template Directories
If you have templates in non-standard locations, add them to `TEMPLATES`:
```python
TEMPLATES = [
{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'DIRS': [
BASE_DIR / 'templates',
BASE_DIR / 'custom_templates', # Custom location
BASE_DIR / 'third_party' / 'templates',
],
'APP_DIRS': True,
},
]
```
### Silencing Specific Checks
To silence specific checks:
```python
# settings.py
SILENCED_SYSTEM_CHECKS = [
'accessible_django.W001', # Silence alt attribute warnings
]
```
To silence checks for specific apps:
```python
# myapp/apps.py
from django.apps import AppConfig
class MyAppConfig(AppConfig):
name = 'myapp'
def ready(self):
# Silence checks for this app only
from django.core.checks import registry
registry.unregister('accessible_django.W001')
```
### Programmatic Access
You can run checks programmatically:
```python
from django.core.checks import run_checks
# Run all checks
issues = run_checks()
# Run only accessibility checks
issues = run_checks(tags=['accessibility'])
# Process issues
for issue in issues:
print(f"{issue.id}: {issue.msg}")
```
## Troubleshooting
### Checks Not Running
**Problem**: Accessibility checks don't appear when running `python manage.py check`
**Solutions**:
1. Verify `accessible_django` is in `INSTALLED_APPS`
2. Check that the app is loaded: `python manage.py shell -c "import accessible_django"`
3. Ensure templates exist in configured directories
### False Positives
**Problem**: Warnings for decorative images with `alt=""`
**Solution**: Empty alt attributes are correct for decorative images. This is not a false positive - the current version flags all missing/empty alt attributes. Future versions will distinguish between decorative and informative images.
### Performance Issues
**Problem**: Checks take too long with many templates
**Solutions**:
1. Limit template directories in `TEMPLATES['DIRS']`
2. Exclude third-party templates
3. Run checks only in development (not in production)
### Template Not Found Errors
**Problem**: `accessible_django.W002: Template could not be found`
**Solutions**:
1. Verify template paths in `TEMPLATES` settings
2. Check file permissions
3. Ensure templates have `.html` extension
## Migration Guide
### From Manual Testing
If you're currently testing accessibility manually:
1. Install AccessibleDjango
2. Run initial check: `python manage.py check`
3. Fix reported issues
4. Add to CI/CD pipeline
5. Continue with automated checks
### From Other Tools
If you're using other accessibility tools:
- AccessibleDjango complements (not replaces) browser-based tools
- Use AccessibleDjango for template-level checks
- Use browser tools for runtime checks
- Combine both for comprehensive coverage
## Future Features
Upcoming accessibility checks (planned):
- Form label validation
- ARIA role verification
- Heading hierarchy checks
- Color contrast analysis
- Keyboard navigation validation
- Link text validation
- Language attribute checks
## Getting Help
- **Documentation**: You're reading it!
- **Issues**: [GitHub Issues](https://github.com/JohananOppongAmoateng/AccessibleDjango/issues)
- **Discussions**: [GitHub Discussions](https://github.com/JohananOppongAmoateng/AccessibleDjango/discussions)
- **Email**: johananoppongamoateng2001@gmail.com
## Next Steps
- Explore the [API Reference](api/index.md) for technical details
- Learn how to [contribute](contributing.md) to the project
- Check the [changelog](changelog.md) for recent updates