Accessibility Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require parvion/accessibility
   php artisan vendor:publish --tag=accessibility-config
   

2. Blade Integration: Place @accessibility directive in your layout file (e.g., resources/views/layouts/app.blade.php).

   @accessibility
   

3. Verify: Refresh your page and check for the accessibility toolbar (default: bottom-right corner).

First Use Case

Enable High Contrast Mode for users with visual impairments:

• Configure in config/accessibility.php:

  'high_contrast' => [
      'enabled' => true,
      'shortcuts' => [
          'enabled' => true,
          'modifiers' => ['alt'],
          'key' => 'c',
      ],
  ],
  

• Test by pressing Alt+C (default shortcut).

Implementation Patterns

Workflows

1. Feature Toggling: Dynamically enable/disable features via config:

   'features' => [
       'font_size' => ['enabled' => true],
       'skip_to_content' => ['enabled' => false], // Disable if redundant
   ],
   

2. Livewire/Alpine Integration: Reinitialize the toolbar after dynamic content updates:

   // Livewire
   window.addEventListener('livewire:navigated', () => {
       window.accessibility?.reinit();
   });
   
   // Alpine.js
   document.addEventListener('alpine:init', () => {
       window.accessibility?.reinit();
   });
   

3. Custom Shortcuts: Override defaults for consistency with your app’s keyboard scheme:

   'global_shortcuts' => [
       'toggle_panel' => [
           'enabled' => true,
           'modifiers' => ['ctrl'],
           'key' => 'a', // Ctrl+A to match your app’s shortcuts
       ],
   ],
   

Integration Tips

• Theme Consistency: Match toolbar colors to your app’s design system:

  'colors' => [
      'primary' => '#2563eb', // Match your primary brand color
  ],
  

• Conditional Loading: Disable the toolbar for admin users or specific routes:

  @if(!auth()->user()->is_admin)
      @accessibility
  @endif
  

• Localization: Translate feature names and tooltips via Laravel’s localization system:

  'labels' => [
      'high_contrast' => __('accessibility.high_contrast'),
  ],
  

Gotchas and Tips

Pitfalls

1. Shortcut Conflicts:

   • Avoid overlapping shortcuts with existing app functionality (e.g., Alt+S for save actions).
   • Debug: Use browser dev tools (Event Listeners tab) to inspect keyboard events.

2. LocalStorage Quirks:

   • Clear localStorage manually if users report persistent settings:

     localStorage.removeItem('accessibility_settings');
     

   • Tip: Disable store_settings in config for testing:

     'store_settings' => env('APP_DEBUG') ? false : true,
     

3. CSS Specificity:

   • Override body classes with higher specificity if needed:

     body.acc-high-contrast {
         background-color: #000 !important;
         color: #fff !important;
     }
     

4. SPA Frameworks:

   • Reinitialize after Turbo/Alpine/Livewire navigation:

     document.addEventListener('turbo:load', () => window.accessibility?.reinit());
     

Debugging

• Console Logs: Enable debug mode in config:

  'debug' => true, // Logs shortcuts and feature toggles to console
  

• Feature Isolation: Test individual features by disabling others in config:

  'features' => [
      'font_size' => ['enabled' => false],
      'high_contrast' => ['enabled' => true], // Test in isolation
  ],
  

Extension Points

1. Custom Features: Extend the toolbar via JavaScript:

   window.accessibility?.registerFeature({
       id: 'custom_feature',
       label: 'Custom Feature',
       toggle: () => {
           document.body.classList.toggle('acc-custom-feature');
       },
   });
   

2. Server-Side Logic: Use middleware to enforce accessibility settings for specific users:

   // app/Http/Middleware/EnforceAccessibility.php
   public function handle($request, Closure $next) {
       if ($request->user()->needs_accessibility) {
           session(['accessibility_override' => true]);
       }
       return $next($request);
   }
   

3. Analytics: Track feature usage (e.g., High Contrast) via Laravel Mixins:

   // app/Providers/AppServiceProvider.php
   use Illuminate\Support\Facades\Blade;
   
   Blade::directive('trackAccessibility', function ($feature) {
       return "<?php session(['accessibility_'.$feature.'_used' => true]); ?>";
   });