ReadlyGo (MVP)

ReadlyGo is a standalone JavaScript accessibility widget designed to run on any HTML site.

Created and maintained by Caleidoscopio Web Agency.

This MVP is frontend-only and zero-backend.

Scope of this MVP

Implemented in v1:

• Visual and readability controls (contrast modes, font tweaks, spacing, alignment, highlights)
• Orientation controls (hide images/emoji, reading mask, reading guide, cursor size)
• Multilanguage UI (English/Italian) with flag switcher in the panel header
• Popup UI + trigger button + local persistence
• Public API + headless event compatibility (readabler-headless)

Install and build

npm install
npm run build

Output files:

• dist/readlygo.esm.js
• dist/readlygo.umd.js

CDN (Ready To Go)

Recommended free stack:

• Load it from jsDelivr in your projects

CDN URLs after publish:

• UMD latest (auto-update): https://cdn.jsdelivr.net/npm/@caleidoscopioweb/readlygo@latest/dist/readlygo.umd.js
• UMD (pin version): https://cdn.jsdelivr.net/npm/@caleidoscopioweb/[email protected]/dist/readlygo.umd.js (Check Version)
• ESM (pin version): https://cdn.jsdelivr.net/npm/@caleidoscopioweb/[email protected]/dist/readlygo.esm.js (Check Version)

Use pinned versions in production to avoid unexpected breaking changes.

CDN snippet (UMD)

<script>
  window.__READLYGO_CONFIG__ = {
    showButton: true,
    defaultLanguage: "en",
    rememberLanguage: true,
    remember: true,
    styleNonce: "",
    assetsBaseUrl: "https://cdn.jsdelivr.net/npm/@caleidoscopioweb/readlygo@latest/assets",
    languageSelector: {
      enabled: true,
      size: 18,
      showCodes: false
    },
    localization: {
      defaultLanguage: "en",
      languages: ["en", "it"],
      flags: {
        en: "https://cdn.jsdelivr.net/npm/@caleidoscopioweb/readlygo@latest/assets/flags/gb.svg",
        it: "https://cdn.jsdelivr.net/npm/@caleidoscopioweb/readlygo@latest/assets/flags/it.svg"
      }
    },
    floatingButton: {
      enabled: true,
      position: "bottom-left",
      variant: "icon",
      iconUrl: "https://cdn.jsdelivr.net/npm/@caleidoscopioweb/readlygo@latest/assets/icons/accessibility-icon.svg",
      iconSize: 22,
      title: "Open accessibility options",
      background: "#b96cbd",
      textColor: "#ffffff",
      iconColor: "#ffffff",
      borderColor: "#a75eab",
      boxShadow: "0 10px 30px rgba(0, 16, 45, 0.28)",
      boxShadowHover: "0 0 0 3px rgba(185, 108, 189, 0.4)",
      padding: "0 10px",
      margin: 24,
      offsetX: 24,
      offsetY: 16
    },
    customTrigger: {
      enabled: true,
      selector: "readlygo-trigger,[data-readlygo-trigger]",
      variant: "icon-text",
      size: "md",
      label: "Accessibility"
    },
    branding: {
      enabled: true,
      text: "Created and maintained by Caleidoscopio Web Agency",
      url: ""
    }
  };
</script>
<script
  src="https://cdn.jsdelivr.net/npm/@caleidoscopioweb/readlygo@latest/dist/readlygo.umd.js"
  defer
  onload="window.ReadlyGo.init(window.__READLYGO_CONFIG__ || {})"
></script>

ESM usage

<script type="module">
  import ReadlyGo from "https://cdn.jsdelivr.net/npm/@caleidoscopioweb/readlygo@latest/dist/readlygo.esm.js";

  ReadlyGo.init({
    showButton: true,
    defaultLanguage: "it",
    rememberLanguage: true,
    languageSelector: {
      enabled: true
    },
    localization: {
      flags: {
        en: "/assets/flags/gb.svg",
        it: "/assets/flags/it.svg"
      }
    },
    floatingButton: {
      position: "bottom-left",
      variant: "icon",
      title: "Open accessibility options",
      background: "#b96cbd",
      textColor: "#ffffff",
      iconColor: "#ffffff",
      borderColor: "#a75eab",
      boxShadow: "0 10px 30px rgba(0, 16, 45, 0.28)",
      boxShadowHover: "0 0 0 3px rgba(185, 108, 189, 0.4)",
      padding: "0 10px",
      margin: 24,
      offsetX: 24,
      offsetY: 16
    },
    openHotkey: "alt+a"
  });
</script>

Multilanguage (EN/IT)

• Built-in locales: English (en) and Italian (it)
• Language switcher is shown in the widget header (flag buttons)
• Change is applied live to title, subtitle, section names, controls, and footer actions
• Set the startup language from script with defaultLanguage: "it" (or en)
• If rememberLanguage: true, selected language is persisted

Custom trigger tag (menu/div)

You can place custom triggers anywhere in HTML:

<readlygo-trigger
  data-rg-variant="icon-text"
  data-rg-label="Accessibility"
  data-rg-size="md"
></readlygo-trigger>

<div
  data-readlygo-trigger
  data-rg-variant="icon"
  data-rg-size="sm"
  data-rg-background="#b96cbd"
  data-rg-text-color="#ffffff"
  data-rg-icon-color="#ffffff"
  data-rg-padding="0 10px"
  data-rg-title="Open accessibility options"
></div>

Supported per-tag options (data-rg-*):

• variant: icon, text, icon-text
• size: sm, md, lg
• label
• icon-url
• icon-size
• background
• text-color (or legacy color)
• icon-color
• padding
• border-color
• box-shadow
• box-shadow-hover (or hover-box-shadow)
• title
• aria-label
• class-name

Public API

• window.ReadlyGo.init(config)
• window.ReadlyGo.dispatch(actionOrPayload, value?)
• window.ReadlyGo.reset()
• window.ReadlyGo.destroy()
• window.ReadlyGo.getState()
• window.ReadlyGo.isReady()
• window.ReadlyGo.normalizeActionName(action)

Examples:

ReadlyGo.dispatch("highlightLinks");
ReadlyGo.dispatch({ action: "fontSizing", value: 2 });
ReadlyGo.reset();

Headless event compatibility

Dispatch from external scripts:

window.dispatchEvent(
  new CustomEvent("readabler-headless", {
    detail: { action: "highlight-links", value: true }
  })
);

Action names are normalized to camelCase, so kebab/snake prefixes are accepted (for example: highlight-links, readlygo-action-highlight-links, mdp-action-highlight-links).

Runtime events:

• ReadlyGoActionChanged
• ReadlyGoLanguageChanged

Supported actions

Value actions:

• contentScaling
• fontSizing
• lineHeight
• letterSpacing

Toggle actions:

• readableFont
• dyslexiaFont
• alignLeft
• alignCenter
• alignRight
• darkContrast
• lightContrast
• monochrome
• highSaturation
• highContrast
• lowSaturation
• highlightTitles
• highlightLinks
• highlightHover
• highlightFocus
• hideImages
• hideEmoji
• readingMask
• readingGuide
• bigBlackCursor
• bigWhiteCursor

Key config options

• storageKey (default: readlygo)
• remember (default: true)
• showButton (default: true)
• startOpen (default: false)
• defaultLanguage (en or it, default: en)
• language (en or it, legacy alias of defaultLanguage)
• rememberLanguage (default: true)
• languageSelector (enabled, size, showCodes)
• localization (defaultLanguage, languages, flags, locales)
• buttonLabel (default: ReadlyGo)
• buttonPosition (bottom-left, bottom-right, top-right, top-left)
• buttonVariant (icon, text, icon-text, default: icon)
• buttonIconUrl (default: built-in white accessibility icon)
• buttonIconSize (default: 22)
• buttonAriaLabel
• buttonTitle
• buttonBackground
• buttonTextColor
• buttonIconColor
• buttonBorderColor
• buttonBoxShadow
• buttonBoxShadowHover
• buttonPadding
• buttonMargin (distance from viewport, px or CSS value)
• buttonOffsetX (horizontal floating offset; defaults to buttonMargin if not set)
• buttonOffsetY (vertical floating offset; defaults to buttonMargin if not set)
• floatingButton (enabled, position, variant, iconUrl, iconSize, label, ariaLabel, title, background, textColor, iconColor, borderColor, boxShadow, boxShadowHover, padding, margin, offsetX, offsetY, aliases marginX, marginY)
• popupTitle (default: ReadlyGo)
• panelSubtitle (default: Accessibility Toolkit)
• closeOnOverlay
• openHotkey (default: alt+a)
• theme (triggerBg, triggerText, triggerIcon, triggerBorder, triggerShadow, triggerShadowHover, triggerPadding, triggerMargin, triggerOffsetX, triggerOffsetY)
• customTrigger (enabled, selector, variant, size, label, iconUrl, iconSize, background, textColor, iconColor, padding, borderColor, title, className)
• branding (enabled, text, url, target, rel)
• enable (action visibility map)
• initialState
• styleNonce (for CSP nonce on injected <style> tags)
• assetsBaseUrl (for OpenDyslexic files in font-dislessici/; if omitted, the runtime tries auto-detection from the script URL)

Browser fallback behavior

• If localStorage is unavailable, state falls back to in-memory runtime storage.

Notes for SPA and dynamic pages

• For route changes, keep a single instance and reuse dispatch/reset.

License

This project is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later).

Copyleft summary:

• If you distribute modified versions of this software, you must keep them under GPL-compatible terms.
• You must keep copyright and license notices.
• You must provide source code of distributed modified versions under the same license terms.

See the LICENSE file for the full legal text.