Color vision deficiency simulator for accessibility testing and design
npm install @allystudio/color-vision-simulatorA JavaScript library for simulating color vision deficiencies (color blindness) on web pages. Useful for accessibility testing, design validation, and educational purposes.
- ๐จ Multiple Color Vision Types: Protanopia, Deuteranopia, Tritanopia, Achromatopsia
- โก High Performance: Direct HTML filter application with overlay fallback
- ๐ง Configurable: Customizable overlay IDs, z-index, and behavior
- ๐ฑ Event-Driven: Subscribe to state changes with callback system
- ๐งน Clean API: Simple functional interface with closure-based state management
- ๐งช Well Tested: Comprehensive test suite with browser testing
- ๐ฆ Zero Dependencies: Lightweight and self-contained
``bash`
npm install @allystudio/color-vision-simulator
`typescript
import { createColorVisionSimulator, COLOR_VISION_PRESETS } from '@allystudio/color-vision-simulator'
// Create a simulator instance
const simulator = createColorVisionSimulator()
// Start simulating protanopia (red-blindness)
simulator.start()
// Change to deuteranopia (green-blindness)
simulator.setVisionType(COLOR_VISION_PRESETS.DEUTERANOPIA)
// Stop simulation
simulator.stop()
`
#### Factory Function
`typescript`
createColorVisionSimulator(options?: SimulatorOptions): ColorVisionSimulator
#### Options
`typescript`
interface SimulatorOptions {
overlayId?: string // Custom overlay ID (default: "color-vision-simulator-overlay")
stylesId?: string // Custom styles ID (default: "color-vision-simulator-styles")
zIndex?: number // Custom z-index (default: 2147483647)
useDirectFilter?: boolean // Use direct HTML filter (default: true)
}
#### Methods
##### State Management
`typescript
// Start the simulation
simulator.start(): void
// Stop the simulation
simulator.stop(): void
// Toggle simulation on/off
simulator.toggle(): void
// Set vision type
simulator.setVisionType(type: ColorVisionType): void
// Configure both vision type and active state
simulator.configure(visionType: ColorVisionType, isActive: boolean): void
`
##### State Queries
`typescript
// Get current state
simulator.getState(): SimulatorState
// Check if active
simulator.isActive(): boolean
// Get current vision type
simulator.getVisionType(): ColorVisionType
`
##### Event Handling
`typescript
// Subscribe to state changes
const unsubscribe = simulator.onStateChange((state) => {
console.log('State changed:', state)
})
// Unsubscribe
unsubscribe()
`
`typescript
type ColorVisionType = 'protanopia' | 'deuteranopia' | 'tritanopia' | 'achromatopsia' | 'normal'
// Presets for convenience
const COLOR_VISION_PRESETS = {
PROTANOPIA: 'protanopia' as const, // Red-blindness
DEUTERANOPIA: 'deuteranopia' as const, // Green-blindness
TRITANOPIA: 'tritanopia' as const, // Blue-blindness
ACHROMATOPSIA: 'achromatopsia' as const, // Total color blindness
NORMAL: 'normal' as const // Normal vision (no simulation)
}
`
`typescript
import {
createColorVisionSimulator,
formatColorVisionType,
getColorVisionDescription
} from '@allystudio/color-vision-simulator'
// Create a new instance
const simulator = createColorVisionSimulator(options)
// Format vision type for display
const displayName = formatColorVisionType('protanopia') // "Protanopia"
// Get description of vision type
const description = getColorVisionDescription('protanopia')
// "Difficulty distinguishing between red and green colors, with red appearing darker"
`
`typescript
import { createColorVisionSimulator, COLOR_VISION_PRESETS } from '@allystudio/color-vision-simulator'
const simulator = createColorVisionSimulator()
// Simulate protanopia
simulator.setVisionType(COLOR_VISION_PRESETS.PROTANOPIA)
simulator.start()
// Later...
simulator.stop()
`
`typescript
const simulator = createColorVisionSimulator()
// Monitor state changes
simulator.onStateChange((state) => {
console.log(Simulation ${state.isActive ? 'started' : 'stopped'})Vision type: ${state.visionType}
console.log()
})
simulator.start()
simulator.setVisionType(COLOR_VISION_PRESETS.DEUTERANOPIA)
simulator.stop()
`
`typescript`
const simulator = createColorVisionSimulator({
overlayId: 'my-color-overlay',
stylesId: 'my-color-styles',
zIndex: 999999,
useDirectFilter: false // Disable direct HTML filtering
})
`typescript
import { formatColorVisionType, getColorVisionDescription } from '@allystudio/color-vision-simulator'
// Format for UI display
const displayName = formatColorVisionType('protanopia') // "Protanopia"
// Get user-friendly description
const description = getColorVisionDescription('deuteranopia')
// "Difficulty distinguishing between red and green colors, with green appearing darker"
// Use in UI components
function VisionTypeSelector({ currentType, onChange }) {
const types = ['protanopia', 'deuteranopia', 'tritanopia', 'achromatopsia', 'normal']
return (
)
}
`
`tsx
import { useEffect, useState } from 'react'
import {
createColorVisionSimulator,
COLOR_VISION_PRESETS,
formatColorVisionType,
type ColorVisionType
} from '@allystudio/color-vision-simulator'
function ColorVisionControls() {
const [simulator] = useState(() => createColorVisionSimulator())
const [isActive, setIsActive] = useState(false)
const [visionType, setVisionType] = useState
useEffect(() => {
const unsubscribe = simulator.onStateChange((state) => {
setIsActive(state.isActive)
setVisionType(state.visionType)
})
return unsubscribe
}, [simulator])
const visionTypes: ColorVisionType[] = [
'protanopia', 'deuteranopia', 'tritanopia', 'achromatopsia', 'normal'
]
return (
value={visionType}
onChange={(e) => simulator.setVisionType(e.target.value as ColorVisionType)}
>
{visionTypes.map(type => (
))}
How It Works
The simulator uses CSS filters to modify the visual appearance of web pages:
1. Color Matrix Filters: For protanopia, deuteranopia, and tritanopia, scientifically accurate color transformation matrices are applied
2. Grayscale Filter: For achromatopsia (total color blindness)
3. Direct HTML Filtering: For better performance, filters are applied directly to the
element when possible
4. Overlay Fallback: When direct filtering isn't suitable, a full-screen overlay with the filter is usedBrowser Support
- Chrome/Edge: Full support
- Firefox: Full support
- Safari: Full support
- Mobile browsers: Full support
Contributing
Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.
License
MIT License - see LICENSE file for details.
Related Packages
-
@allystudio/accessibility-utils - Accessibility analysis utilities
- @allystudio/element-inspector` - DOM element inspection tools