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

This creates /node_modules/cogjs/dist/cog.min.js, which can be included directly in your HTML pages or moved to your assets` folder.

CDN

You can load CogJS directly from a CDN, but some browsers may block or delay script execution from dynamic sources, some people have mentioned. If you encounter issues using the script via CDN, it's recommended to download it manually and serve it locally.

https://cdn.jsdelivr.net/npm/cogjs@latest/dist/cog.min.js

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>

    <div cog-toggle-content>
        <div>Simple version of the text</div>
        <div>More detailed explanation of the same content</div>
        <div>The full article</div>
    </div>
    
    <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>

    <form cog-chunk>
        <fieldset>
            <legend>Choose Your Plan</legend>
            <label>
                <input type="radio" name="plan" value="basic"> Basic
            </label>
            <label>
                <input type="radio" name="plan" value="pro"> Pro
            </label>
            <label>
                <input type="radio" name="plan" value="premium"> Premium
            </label>
        </fieldset>

        <fieldset>
            <legend>Enter Your Details</legend>
            <label>
                Full Name: <input type="text" name="name" required>
            </label><br>
            <label>
                Email: <input type="email" name="email" required>
            </label>
        </fieldset>

        <fieldset>
            <legend>Confirm & Submit</legend>
            <p>Please review your information before submitting.</p>
            <button type="submit">Submit</button>
        </fieldset>
    </form>

    <section>
        <label cog-hint="The first part of your email address before the @">
            Username:
            <input type="text" name="username">
        </label>
    </section>
    
</main>

<!-- Load CogJS from CDN and initialize it -->
<script src="/node_modules/cogjs/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. Configurable via `cogReadConfig` or `cogConfig.read`
`cog-toggle-content`	Enables toggle between multiple versions of content (e.g., simplified vs detailed text). Only requires two or more child `<div>`s
`cog-chunk`	Splits content into visible steps. Adds Prev/Next buttons and keyboard support for progressive disclosure.
`cog-hint="Hint text"`	Shows a tooltip-style contextual hint on focus or idle. Helps guide users through interaction gently.

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

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

More attributes coming soon:

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.