CogJS - Cognitive-Oriented Web Accessibility Toolkit

CogJS is a production-ready JavaScript library that enhances web accessibility for neurodivergent and cognitively diverse users. Designed for flexibility and minimal setup, CogJS lets developers declaratively add support for cognitive needs using custom HTML attributes-no complex tooling or frameworks required.

Why CogJS?

Traditional accessibility tooling focuses heavily on screen readers and mobility devices, but often overlooks the needs of users with:

Autism Spectrum Conditions (ASC)
ADHD / ADD
Dyslexia
Sensory Processing Disorders
Cognitive fatigue or executive functioning difficulties

CogJS bridges this gap, empowering developers to:

Reduce cognitive load
Enhance readability and user control
Provide sensory-friendly experiences
Respect user preference with simple, declarative markup

Installation

Install via npm:

npm install cogjs

To build a minified browser-ready version:

npm run build

This creates dist/cog.min.js, which can be included directly in your HTML pages.

Usage

QUICK START: Static HTML via CDN

You can use CogJS in a static HTML file without any build process:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>CogJS CDN Demo</title>

  <!-- Define config before loading the script -->
  <script>
    window.cogThemeConfig = {
      defaultTheme: 'dyslexic-yellow',
      themes: {
        'dyslexic-yellow': {
          background: '#fffce0',
          foreground: '#000'
        },
        'dyslexic-blue': {
          background: '#e6f0ff',
          foreground: '#000'
        },
        'dark-mode': {
          background: '#1e1e1e',
          foreground: '#fff'
        }
      },
      targets: {
        background: ['body', 'section', 'header'],
        foreground: ['h1', 'p', 'li', 'a']
      }
    };

    window.cogConfig = {
      active: true,
      animation: {
        default: true,
        respectSystemPref: true,
        styles: `
          .cog-no-animation *,
          .cog-no-animation {
            animation: none !important;
            transition: none !important;
            scroll-behavior: auto !important;
          }
        `
      },
      background: window.cogThemeConfig
    };
  </script>


  <style>
    body {
      font-family: sans-serif;
      padding: 2rem;
    }
    section {
      padding: 1rem;
      margin-bottom: 1rem;
      border: 1px solid #ccc;
    }
  </style>
</head>
<body cog-background="dyslexic-yellow">

<header>
    <h1>CogJS CDN Demo</h1>
    <p>This page demonstrates CogJS via CDN in a static HTML file.</p>
</header>

<main>
    <section>
    <p>This section uses the default theme defined on the body.</p>
    </section>
    
    <section cog-animation="false">
    <p>This section disables all animations.</p>
    </section>
    
    <section cog-active="false">
    <p>This section opts out of all CogJS features.</p>
    </section>

    <section cog-read>
        <p>This content will be read aloud when the button is clicked.</p>
    </section>
</main>

<!-- Load CogJS from CDN and initialize it -->
<script src="dist/cog.min.js"></script>
<script>
    window.initCogAccessibility?.();
</script>


</body>
</html>

⚛️ React

import { initCog } from 'cogjs';
useEffect(() => {
  initCog();
}, []);

🖖 Vue

import { initCog } from 'cogjs';
mounted() {
  initCog();
}

🅰️ Angular

import { initCog } from 'cogjs';
ngAfterViewInit() {
  initCog();
}

Attributes & Features

Attribute	Description
`cog-background="theme"`	Applies background/foreground theme based on accessibility preference (e.g., dyslexic-yellow, dark-mode)
`cog-animation="false"`	Disables transitions and motion for the element and its children
`cog-active="false"`	Completely disables CogJS features for the target element and all descendants
`cog-read`	Adds a speech synthesis button to read content aloud. Can be styled and configured via `cogReadConfig` or `cogConfig.read`.

Themes, animation behavior, and target selectors are all configurable via:

config/cog-config.js
config/cog-theme.js

More attributes coming soon:

cog-read
cog-chunk
cog-highlight

Custom Configuration

CogJS uses a simple, declarative configuration system that lives in:

/config/
├── cog-config.js    # Core settings for CogJS behavior
└── cog-theme.js     # Background and foreground color themes

A barebones default config is included in the package with:

// config/cog-config.js
window.cogConfig = {
  active: true,
  animation: {
    default: true,
    respectSystemPref: true,
    styles: `
      .cog-no-animation *,
      .cog-no-animation {
        animation: none !important;
        transition: none !important;
        scroll-behavior: auto !important;
      }
    `
  },
  background: window.cogThemeConfig
};

Customise it by editing these values or overriding the window.cogConfig object before calling initCog(). You can define your own themes in cog-theme.js:

// config/cog-theme.js
window.cogThemeConfig = {
  defaultTheme: 'none',
  themes: {
    'dyslexic-yellow': { background: '#fffce0', foreground: '#000' },
    'dark-mode': { background: '#1e1e1e', foreground: '#fff' }
  },
  targets: {
    background: ['body', 'section'],
    foreground: ['p', 'h1', 'h2', 'li']
  }
};

You can override read default settings using this customised config.

// config/cog-read-config.js
window.cogReadConfig = {
  read: {
    label: "Speak text",
    iconSize: "1.25rem",
    styles: `
      .cog-read-button {
        background-color: #007acc;
        color: white;
        border-radius: 4px;
        padding: 0.25rem;
      }
      .cog-read-button:hover {
        background-color: #005fa3;
      }
      .cog-read-button svg {
        fill: white;
      }
    `
  }
};

License

Licensed under the MIT License.

CogJS is not a replacement for WCAG conformance-it’s a powerful supplement that helps designers and developers build more inclusive, user-friendly experiences for everyone.