Accessibility Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require artisanpack-ui/accessibility
   

   Publish the config file (if needed):

   php artisan vendor:publish --tag=artisanpack-package-config
   

2. First Use Case Check color contrast for a background/text pair:

   use ArtisanPack\Accessibility\Facades\Accessibility;
   
   $isAccessible = Accessibility::checkContrast('#3b82f6', '#ffffff'); // true
   

3. Key Facade Methods

   • Accessibility::checkContrast($bgColor, $textColor)
   • Accessibility::getContrastColor($bgColor)
   • Accessibility::simulateColorBlindness($color, $type = 'protanopia')

Where to Look First

• Facade API: vendor/artisanpack-ui/accessibility/src/Facades/Accessibility.php
• Core Helpers: vendor/artisanpack-ui/accessibility/src/Core/Accessibility.php
• Configuration: config/artisanpack/accessibility.php

Implementation Patterns

1. Dynamic Component Styling

Pattern: Automatically generate accessible colors in Blade components

// app/View/Components/AccessibleButton.php
public function __construct(string $bgColor = '#3b82f6') {
    $this->bgColor = $bgColor;
    $this->textColor = Accessibility::getContrastColor($bgColor);
}

Usage:

<x-accessible-button bg-color="#dc2626">Delete</x-accessible-button>

2. Livewire Integration

Pattern: Validate form inputs for accessibility

// app/Http/Livewire/AccessibleForm.php
public function updated($field) {
    $color = $this->$field;
    $this->textColor = Accessibility::getContrastColor($color);
    $this->isAccessible = Accessibility::checkContrast($color, $this->textColor);
}

3. Theming System

Pattern: Generate color palettes with contrast validation

// Generate a WCAG-compliant palette
$palette = Accessibility::generatePalette([
    '#2563eb', // blue-800
    '#10b981', // emerald-600
    '#dc2626'  // red-600
]);

4. API Response Validation

Pattern: Validate UI colors before saving to database

// app/Http/Controllers/ThemeController.php
public function store(Request $request) {
    $request->validate([
        'primary_color' => [
            'required',
            function ($attribute, $value, $fail) {
                if (!Accessibility::checkContrast($value, Accessibility::getContrastColor($value))) {
                    $fail('Color must have sufficient contrast with its text color.');
                }
            }
        ]
    ]);
}

5. Cache Optimization

Pattern: Cache contrast calculations for performance

// app/Providers/AppServiceProvider.php
public function boot() {
    Cache::shouldUse('accessibility');
    Accessibility::setCache(new FileCache(storage_path('framework/cache/accessibility')));
}

Gotchas and Tips

Common Pitfalls

1. Color Format Mismatches

   • Issue: Hex colors (#3b82f6) work, but rgb(59, 130, 246) may fail if not properly normalized
   • Fix: Use Accessibility::normalizeColor():

     $normalized = Accessibility::normalizeColor('rgb(59, 130, 246)'); // returns '#3b82f6'
     

2. Configuration Path Changes

   • Issue: Old config references (config('accessibility.*')) break after v2.1.1
   • Fix: Update to config('artisanpack.accessibility.*')

3. Laravel Version Conflicts

   • Issue: Laravel 13 requires PHP 8.3+
   • Fix: Check composer.json constraints:

     "require": {
         "php": ">=8.3",
         "laravel/framework": "^13.0"
     }
     

4. Color Blindness Simulation

   • Issue: simulateColorBlindness() returns unexpected results
   • Fix: Specify the type:

     // Common types: 'protanopia', 'deuteranopia', 'tritanopia', 'achromatopsia'
     $simulated = Accessibility::simulateColorBlindness('#3b82f6', 'deuteranopia');
     

Debugging Tips

1. Enable Detailed Reports

   Accessibility::setReportingMode(true);
   $report = Accessibility::checkContrast('#3b82f6', '#ffffff', true);
   

2. Check WCAG Compliance Levels

   $result = Accessibility::checkContrast('#3b82f6', '#ffffff', false, 'AAA');
   // Returns true/false for AAA compliance
   

3. Validate Entire Palettes

   $palette = [
       'primary' => '#2563eb',
       'secondary' => '#10b981',
       'text' => '#1f2937'
   ];
   $report = Accessibility::validatePalette($palette);
   

Performance Optimization

1. Cache Contrast Calculations

   Cache::remember('contrast_'.$bgColor, 86400, function() use ($bgColor) {
       return Accessibility::getContrastColor($bgColor);
   });
   

2. Batch Processing

   $colors = ['#3b82f6', '#10b981', '#dc2626'];
   $results = Accessibility::batchCheckContrast($colors, '#ffffff');
   

Extension Points

1. Custom Color Formats

   // Register a new format plugin
   Accessibility::registerColorFormat('tailwind', function($value) {
       return str_replace(['-', ''], '', $value); // Convert 'blue-500' to '#3b82f6'
   });
   

2. Plugin System

   // Create a custom accessibility rule
   Accessibility::registerPlugin(new class implements AccessibilityRulePluginInterface {
       public function check($context) {
           // Custom logic
           return new ResultSet(true, 'Custom rule passed');
       }
   });
   

3. Event Listeners

   // Listen for contrast checks
   event(new ContrastChecked($bgColor, $textColor, $result));
   

Configuration Quirks

1. Default Values

   // config/artisanpack/accessibility.php
   'defaults' => [
       'contrast_ratio' => 4.5, // AAA compliance
       'color_blindness_types' => ['protanopia', 'deuteranopia']
   ]
   

2. Dynamic Configuration

   // Override defaults per request
   config(['artisanpack.accessibility.contrast_ratio' => 3.0]);