♿ @valuestocks/accessibility

Framework-agnostic web accessibility widget — Web Components, React adapter, 7 profiles, 20+ tools, i18n.

A zero-dependency accessibility enhancement suite that adds a floating button to any website. Clicking it opens a sidebar panel with one-click accessibility profiles, granular text & color adjustments, readability aids, and navigation tools — all applied instantly via CSS custom properties. Built for Next.js, React, and vanilla JS.

📖 Table of Contents

• What Are Accessibility Profiles?
• Profile Types
• Features & Tools
• 7W — The Essentials
• Quick Start
• Configuration
• Architecture
• Keyboard Shortcuts
• Browser Support
• Publishing

🧠 What Are Accessibility Profiles?

Accessibility profiles are pre-configured bundles of accessibility settings designed for specific needs. Instead of requiring users to toggle 16 individual tools one-by-one, they can click a single profile card and instantly apply the optimal combination of: font scaling, contrast modes, cursor size, animation control, focus indicators, text spacing, and more.

Think of profiles as "presets for inclusion" — each one crafted for a different way of interacting with the web.

Why Profiles Matter

| Without Profiles | With Profiles | |---|---| | User must discover and understand 16+ individual settings | One click applies the right combination | | Trial-and-error to find the right mix | Research-backed presets for each need | | Overwhelming for non-technical users | Simple, descriptive, icon-labeled cards | | Settings conflict (e.g., high-contrast + low-saturation) | Profiles are internally consistent | | No guidance on what "good" looks like | Each profile explains what it does and who it helps |

Accessibility isn't just about compliance — it's about ensuring every visitor can consume your content, regardless of ability.

🏷️ Profile Types

Each profile applies a specific set of states (tools) optimized for a particular need. Profiles are one-shot — clicking one clears any previously active profile and applies the new preset.

1. 👁️ Vision Impaired

Boosts text size and contrast for users with low vision.

| Setting | Value | |---|---| | Font Size | 150% | | Font Weight | Bold | | Contrast | High Contrast | | Big Cursor | Enabled | | Visible Focus | Enabled | | Highlight Links | Enabled | | Highlight Titles | Enabled |

Ideal for: seniors, macular degeneration, glaucoma, cataracts, refractive errors.

2. 🧩 Cognitive Disability

Applies dyslexia-friendly font and enhanced readability.

| Setting | Value | |---|---| | Dyslexia Font | Enabled | | Letter Spacing | Increased | | Line Height | Increased | | Font Weight | Bold | | Highlight Links | Enabled | | Reading Guide | Enabled |

Ideal for: dyslexia, dyscalculia, learning disabilities, low literacy, non-native speakers.

3. ⌨️ Keyboard Navigation

Bigger cursor, larger click targets, and visible focus for keyboard-only users.

| Setting | Value | |---|---| | Visible Focus | Enabled | | Big Cursor | Enabled | | Stop Animations | Enabled |

Ideal for: motor disabilities, Parkinson's, cerebral palsy, arthritis, RSI, keyboard-only navigation.

4. 🦾 Motor Impaired

Big cursor, reading guide, and reduced motion for motor control difficulties.

| Setting | Value | |---|---| | Big Cursor | Enabled | | Visible Focus | Enabled | | Stop Animations | Enabled | | Reduced Motion | Enabled | | Reading Guide | Enabled |

Ideal for: motor control difficulties, tremors, limited fine motor control, users who benefit from reduced motion and reading aids.

5. ⚡ Seizure Safe

Stops all animations and motion effects that may trigger seizures or vestibular disorders.

| Setting | Value | |---|---| | Stop Animations | Enabled | | Reduced Motion | Enabled | | High Contrast | Disabled | | Monochrome | Disabled | | Low Saturation | Disabled |

Ideal for: photosensitive epilepsy, vestibular disorders, migraines, motion sickness.

6. 🦯 Blind / Screen Reader

Maximum font size, high contrast, and screen-reader-compatible navigation.

| Setting | Value | |---|---| | Font Size | 200% | | Font Weight | Bold | | Contrast | High Contrast | | Big Cursor | Enabled | | Visible Focus | Enabled | | Stop Animations | Enabled |

Ideal for: screen reader users, severe low vision, legal blindness, NVDA/JAWS/VoiceOver users.

7. 🧠 ADHD Friendly

Reading mask and focus highlight to reduce distractions.

| Setting | Value | |---|---| | Focus Mode | Enabled | | Stop Animations | Enabled | | Reading Ruler | Enabled | | Line Height | Increased | | Visible Focus | Enabled |

Ideal for: ADHD, attention disorders, executive dysfunction, sensory processing issues.

🔧 Features & Tools

📝 Content Adjustments

| Tool | Description | |---|---| | Font Size | Stepped control (10%–200%) with live preview | | Font Weight | Toggle bold text for improved legibility | | Line Height | Adjustable spacing (1.0x–3.0x) between lines | | Letter Spacing | Adjustable character spacing (0–10px) | | Dyslexia Font | Switches to a dyslexia-friendly typeface | | Highlight Links | Underlines and emphasizes all hyperlinks | | Highlight Titles | Emphasizes heading elements (h1–h6) | | Hide Images | Hides all images and media to reduce visual distraction | | Content Scaling | Global page zoom via CSS transform |

↔️ Text Alignment

| Tool | Description | |---|---| | Align Left | Align text to the left edge | | Align Center | Center text horizontally | | Align Right | Align text to the right edge | | Justify Text | Distribute text evenly between margins |

🎨 Color & Contrast

| Tool | Description | |---|---| | High Contrast | Maximum contrast between text and background | | Light Contrast | Soft, reduced-contrast palette | | Dark Contrast | Dark background with light text | | Monochrome | Grayscale mode — removes all color | | Low Saturation | Muted, desaturated color palette | | High Saturation | Intensified colors for better differentiation | | Invert Colors | Full color inversion (dark↔light) |

📖 Readability

| Tool | Description | |---|---| | Readable Font | Switches to a highly legible font family | | Highlight Links | Underlines and emphasizes all hyperlinks | | Highlight Titles | Emphasizes heading elements (h1–h6) | | Reading Guide | Horizontal line following cursor for line-tracking | | Reading Ruler | Vertical highlight bar for focused reading | | Reading Mask | Translucent overlay with a transparent slit that follows the mouse | | Screen Reader | Adds skip links and enhances page structure for screen reader users | | Focus Mode | Dims everything except the focused element |

🧭 Navigation & Focus

| Tool | Description | |---|---| | Big Cursor | Enlarges the mouse cursor for visibility | | Visible Focus | Bold focus ring on all interactive elements | | Focus Mode | Dims everything except the focused element |

🎬 Motion & Animation

| Tool | Description | |---|---| | Stop Animations | Freezes all CSS animations and transitions | | Reduced Motion | Applies prefers-reduced-motion media query defaults |

🌐 Internationalization (i18n)

| Language | Code | Coverage | |---|---|---| | English | en | 100% | | Hindi (हिन्दी) | hi | 100% |

Architecture supports 40+ languages — add locale JSON files to extend.

❓ 7W — The Essentials

What?

@valuestocks/accessibility is an open-source, framework-agnostic accessibility widget that adds a floating toolbar to any website. It provides one-click accessibility profiles and granular control over text, color, readability, and navigation.

Why?

Over 1 billion people (15% of the global population) live with some form of disability. The web should be usable by everyone — not just those with perfect vision, motor control, and cognitive focus. This widget bridges the gap between compliance requirements (WCAG, ADA, Section 508) and genuine user experience.

Who?

• End users — Anyone with visual, cognitive, motor, or attention-related needs
• Developers — Adding accessibility to Next.js, React, or vanilla JS projects
• Businesses — Meeting WCAG 2.1 AA compliance without rebuilding the entire UI
• Government & Education — Public-sector sites with mandatory accessibility requirements

When?

• During development — Integrate early to build inclusive products from day one
• Post-launch — Add as a drop-in enhancement to existing sites
• For compliance audits — Satisfies multiple WCAG success criteria (1.4.4 Resize Text, 1.4.3 Contrast, 2.2.2 Pause/Stop/Hide, 2.4.7 Focus Visible)

Where?

Any web application — Next.js, React, Vue, Svelte, Angular, Laravel, static HTML. The core is vanilla JS with Web Components; the React adapter provides idiomatic hooks and context.

Which?

Choose the integration that fits your stack:

• React/Next.js? → @valuestocks/accessibility/react
• Vanilla JS? → @valuestocks/accessibility (core)
• Laravel? → Companion PHP package (Blade components + API routes)

How?

1. Site loads → floating accessibility button appears in the corner
2. User clicks button → sidebar panel slides open
3. User clicks a profile OR toggles individual tools
4. CSS custom properties are injected into the page instantly
5. Settings are saved to localStorage → persist across visits
6. Keyboard shortcuts (Alt+A, Alt+R, Esc) provide alternative navigation

🚀 Quick Start

React / Next.js

// app/layout.tsx
import { AccessibilityEngine } from '@valuestocks/accessibility'
import { localStorageAdapter } from '@valuestocks/accessibility'
import { AccessibilityProvider, AccessibilityWidget } from '@valuestocks/accessibility/react'

const engine = new AccessibilityEngine({ storage: localStorageAdapter })

export default function RootLayout({ children }) {
  return (
    <AccessibilityProvider engine={engine} autoInit showWidgetOnMount>
      {children}
    </AccessibilityProvider>
  )
}

React with Project-Level Config

// src/config/accessibility.config.ts
import { mergeConfig } from '@valuestocks/accessibility'

export default mergeConfig({
  side: 'right',
  features: {
    tools: {
      'monochrome': true,
      'readable-font': true,
      'highlight-links': true,
    },
    languageChange: true,
  },
})

Vanilla JS / Any Framework

import { AccessibilityEngine, localStorageAdapter, createAccessibilityUI } from '@valuestocks/accessibility'

const engine = new AccessibilityEngine({ storage: localStorageAdapter })
await engine.init()
createAccessibilityUI(engine, {
  position: 'bottom-right',
  config: { side: 'right' }
})

Apply a Profile Programmatically

// Apply the "Vision Impaired" profile on a button click
engine.applyProfile('vision-impaired')

// Apply "Seizure Safe" for users with epilepsy
engine.applyProfile('seizure-safe')

// Reset all settings to default
engine.reset()

Inline Panel (Settings Page)

import { AccessibilityPanel } from '@valuestocks/accessibility/react'

export default function SettingsPage() {
  return (
    <div>
      <h2>Accessibility Settings</h2>
      <AccessibilityPanel />
    </div>
  )
}

⚙️ Configuration

Full Configuration Schema

interface IAccessibilityConfig {
  side?: 'right' | 'left'                        // Panel slide direction
  defaultLanguage?: string                       // Fallback locale (default: 'en')
  lang?: string                                  // Initial language
  position?: 'bottom-left' | 'bottom-right'       // Floating button position
            | 'top-left' | 'top-right'
  offset?: [number, number]                      // [x, y] px from edge (default: [20, 20])
  blur?: boolean                                 // Backdrop blur when open (default: true)
  features?: {
    tools?: Record<string, boolean>              // Enable/disable individual tools
    profiles?: Record<string, boolean>            // Enable/disable individual profiles
    languageChange?: boolean                     // Show language switcher
    shortcuts?: boolean                          // Show keyboard shortcuts card
  }
  hooks?: {
    onAction?: (event: {
      action: string
      id?: string
      value?: unknown
      states: Record<string, unknown>
    }) => void                                   // Analytics / custom callback
  }
}

Example: Full Custom Config

import { mergeConfig } from '@valuestocks/accessibility'

const config = mergeConfig({
  side: 'left',
  blur: false,
  position: 'bottom-left',
  offset: [32, 32],
  features: {
    tools: {
      'font-size': true,
      'font-weight': true,
      'line-height': true,
      'letter-spacing': true,
      'readable-font': true,
      'highlight-links': true,
      'monochrome': true,
      'invert': false,
      'big-cursor': false,
      'stop-animations': false,
      'reading-guide': false,
      'reading-ruler': false,
      'focus-mode': false,
      'visible-focus': false,
      'reduced-motion': false,
    },
    profiles: {
      'seizure-safe': true,
      'vision-impaired': true,
      'adhd-friendly': true,
      'cognitive-disability': true,
      'keyboard-navigation': true,
      'blind-users': true,
    },
    languageChange: true,
    shortcuts: true,
  },
  hooks: {
    onAction: (event) => {
      // Send accessibility usage to analytics
      console.log('Accessibility action:', event.action, event.id)
    },
  },
})

🧩 Architecture

@valuestocks/accessibility/
├── engine/          AccessibilityEngine — main orchestrator
├── state/           StateManager — observable preference store
├── storage/         localStorage & in-memory adapters
├── css/             CSS generator & injector (Shadow DOM)
├── tools/           16 accessibility tools (config-driven)
│   ├── content/     font-size, weight, line-height, spacing, dyslexia-font
│   ├── color/       contrast modes, invert, saturation, monochrome
│   ├── readability/ reading guide, reading ruler, focus mode
│   ├── motion/      stop animations, reduced motion
│   └── navigation/  big cursor, visible focus
├── profiles/        6 preset accessibility profiles
├── i18n/            English + Hindi (40+ language ready)
├── ui/              Web Components (asw-widget, asw-menu, asw-toggle, asw-slider)
├── config/          Configuration schema, defaults, mergeConfig
├── react/           React adapter (provider, hooks, components)
└── types/           TypeScript type definitions

Subpath Exports

| Import | Contains | |---|---| | @valuestocks/accessibility | Core: Engine, state, storage, tools, profiles, i18n, UI, CSS, config | | @valuestocks/accessibility/react | React: AccessibilityProvider, hooks, AccessibilityWidget, AccessibilityPanel |

⌨️ Keyboard Shortcuts

| Key | Action | |---|---| | Alt + A | Toggle panel open/close | | Alt + R | Reset all settings to default | | Esc | Close panel | | Tab / Shift + Tab | Navigate panel elements (focus trapped inside) |

On macOS, Alt is the Option (⌥) key.

🌐 Browser Support

| Browser | Version | |---|---| | Chrome | 90+ | | Firefox | 90+ | | Safari | 15+ | | Edge | 90+ |

Uses Web Components (CustomElement v1) with Shadow DOM for fully encapsulated styles. No IE11 support.

🧪 Testing

npm test              # Run all 99 tests
npm run test:watch    # Watch mode
npm run lint          # Type check

99 tests covering engine, state, storage, tools, profiles, CSS generation, i18n, icons, React integration, and CSP compliance.

📦 Publishing

cd packages/accessibility
npm login
npm publish --access public

prepublishOnly hook runs npm run build automatically — dist is always fresh.

📄 License

MIT © ValueStocks