@allystudio/color-vision-simulator

A JavaScript library for simulating color vision deficiencies (color blindness) on web pages. Useful for accessibility testing, design validation, and educational purposes.

Features

- 🎨 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

Installation

``bash
npm install @allystudio/color-vision-simulator
`

Quick Start

`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()
`

API Reference

$3

#### 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()
`

$3

`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)
}
`

$3

`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"
`

Examples

$3

`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()
`

$3

`typescript
const simulator = createColorVisionSimulator()

// Monitor state changes
simulator.onStateChange((state) => {
console.log(Simulation ${state.isActive ? 'started' : 'stopped'})
console.log(Vision type: ${state.visionType})
})

simulator.start()
simulator.setVisionType(COLOR_VISION_PRESETS.DEUTERANOPIA)
simulator.stop()
`

$3

`typescript
const simulator = createColorVisionSimulator({
overlayId: 'my-color-overlay',
stylesId: 'my-color-styles',
zIndex: 999999,
useDirectFilter: false // Disable direct HTML filtering
})
`

$3

`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 (
onChange(e.target.value)}>
{types.map(type => (

{formatColorVisionType(type)}

))}

)
}
`

$3

`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('protanopia')

useEffect(() => {
const unsubscribe = simulator.onStateChange((state) => {
setIsActive(state.isActive)
setVisionType(state.visionType)
})

return unsubscribe
}, [simulator])

const visionTypes: ColorVisionType[] = [
'protanopia', 'deuteranopia', 'tritanopia', 'achromatopsia', 'normal'
]

return (



)
}
`

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 used

Browser 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