Accessibility Panel for Low-Vision and Visually Impaired Users

@delement/vi-panel is a TypeScript accessibility widget that adds a low-vision mode, also known as a visually impaired version, to websites and web applications. The package provides an accessible control panel for font size, font family, line spacing, color contrast, image visibility, speech synthesis, page reading, and voice commands.

Use it when you need a configurable website accessibility panel, a WCAG-oriented low-vision toolbar, or a ready-made visually impaired mode for an existing frontend without rebuilding the whole design system.

Accessibility Widget Features

• Low-vision and visually impaired mode for websites, portals, and web applications.
• Accessibility controls for font size, font family, letter spacing, line height, color contrast, monochrome mode, and image visibility.
• Speech synthesis for panel controls and full-page reading with browser Web Speech APIs.
• Voice command support when speech recognition is available in the browser.
• Persistent user settings in localStorage for repeat visits.
• External open and close triggers through data-js-vipanel-toggle.
• Optional floating accessibility button rendered automatically by the package.
• Configurable style scope, ignored elements, hidden elements, captcha exclusions, and page reading areas.
• TypeScript declarations for public configuration, panel state, and event payloads.

Install Accessibility Panel

npm i @delement/vi-panel
# or
yarn add @delement/vi-panel
# or
pnpm add @delement/vi-panel

Add Low-Vision Mode

import { ViPanel } from "@delement/vi-panel";

new ViPanel();

<button data-js-vipanel-toggle>
  Low-vision version
</button>

By default, the accessibility panel is rendered into document.body. ViPanel is a singleton, and the active instance is exposed as window.ViPanel.

Configure the Visually Impaired Mode

import { ViPanel } from "@delement/vi-panel";
import type { IViPanelConfig } from "@delement/vi-panel";

const config: IViPanelConfig = {
  /**
   * Media query that disables or closes the accessibility panel while it matches.
   */
  visibleUntil: "(max-width: 350px)",
  /**
   * Areas where low-vision styles are applied.
   */
  targetSelectors: [ "body" ],
  /**
   * Keeps the panel fixed while the page scrolls.
   */
  isFixed: true,
  /**
   * Content areas used by the "Read page" action.
   */
  pageUtterSelectors: [ "main" ],
  /**
   * Elements hidden while low-vision mode is open.
   */
  hiddenElementsSelectors: [ ".site-banner" ],
  /**
   * Elements excluded from panel styling.
   */
  ignoreElementsSelectors: [ ".map-widget" ],
  /**
   * Captcha selectors handled the same way as ignored elements.
   */
  captchaElementsSelectors: [ "[class*='captcha']" ],
  /**
   * Values used by the font-size accessibility controls.
   */
  fontSizeSettings: {
    fontSizeSmall: "14px",
    fontSizeStandard: "default",
    fontSizeLarge: "20px",
  },
  /**
   * Initial CSS variable values applied on first open and reset.
   * Use "default" to clear a panel-controlled value.
   */
  defaultSettings: {
    deViBaseFontSize: "default",
    deViBaseFontFamily: "sans-serif",
    deViBaseLetterSpacing: "default",
    deViBaseLineHeight: "1.5",
    deViBaseBgColor: "default",
    deViBaseFontColor: "default",
    deViFilter: "default",
    deViImagesDisplay: "default",
  },
  /**
   * Enables speech synthesis for accessibility panel control labels.
   */
  isShouldUtterControls: true,
  /**
   * Query parameter that opens the panel automatically.
   */
  openPanelQueryParam: "openVI",
  /**
   * Settings for the auto-rendered accessibility toggle button.
   */
  autoAddBtnCfg: {
    /**
     * Enables auto-rendering of the toggle button.
     */
    isEnabled: true,
    /**
     * Horizontal side of the viewport.
     */
    side: "right",
    /**
     * Vertical position of the toggle button.
     */
    position: {
      top: "auto",
      bottom: "32px",
    },
    /**
     * Label used while the visually impaired mode is closed.
     */
    openText: "Low-vision version",
    /**
     * Label used while the visually impaired mode is open.
     */
    closeText: "Standard version",
  },
};

new ViPanel(config);

The auto-rendered button receives the public class deViPanelToggleBtn for external styling.

DOM Configuration for Accessibility Settings

The package can read accessibility configuration from data-js-vipanel-cfg on body. The object passed to the constructor has priority over DOM configuration.

<body data-js-vipanel-cfg='{"visibleUntil":"(max-width: 350px)"}'>

Accessibility Panel Events

The panel emits viPanel::isInteracted on both open and close. Use this event to integrate the low-vision mode with analytics, layout state, or custom application logic.

import type { IViPanelInteractedEventDetail } from "@delement/vi-panel";

document.documentElement.addEventListener("viPanel::isInteracted", (event) => {
  const detail = (event as CustomEvent<IViPanelInteractedEventDetail>).detail;

  console.debug(detail.isOpened, detail.settings, detail.isShouldUtterControls);
});

The event detail shape is:

interface IViPanelInteractedEventDetail {
  isOpened: boolean;
  settings: Record<string, string>;
  isShouldUtterControls: boolean;
}

TypeScript Exports

Generated declaration files export public types as they are named in source. They are not re-exported under alias names.

import type {
  IDefaultSettings,
  IFontSizeSettings,
  IViPanelAutoAddBtnCfg,
  IViPanelConfig,
  IViPanelInteractedEventDetail,
  IViPanelState,
  TToggleSide,
} from "@delement/vi-panel";

The package entry also exports ViPanel as the primary runtime API.

Runtime Notes

• State is persisted in localStorage using stable keys: viSettings, viIsOpened, and viIsShouldUtterControls.
• The module assigns the active singleton instance to window.ViPanel.
• Voice recognition and speech synthesis depend on browser support and user permissions.

Documentation

Full accessibility panel documentation and examples are available on the D-Element UI portal in the public packages section: https://ui.d-element.ru