cogjs

v0.0.36

Published

7 months ago

CogJS is a lightweight, modular JavaScript library for cognitive and neurodivergent accessibility on the web.

0High
0Medium
0Low

gslinn

accessibility a11y cognitive neurodivergent web html javascript inclusive-design

CogJS - Cognitive-Oriented Web Accessibility Toolkit

CogJS uses simple attributes to make the web easier for people with cognitive and neurological differences, it's a lightweight blueprint for a more inclusive future.

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.

Main Documentation

For a more granular set of documents use this link. Accessible User Interface Guidelines (AUIG).

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

DEMO

As this project progresses I will create a better set of demos but in the meantime this should provide some additional insight. Checkout the sandbox demo.

QUICK START: Static HTML

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>

  <!-- Theme script if you're using cog-background -->
    <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: ["p", "li", "a"],
            },
        };
    </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>
    <nav cog-path></nav>
</header>

<main>

    <section>
        <form cog-remind="5s:Don't forget to click Submit!">
            <input type="text" />
            <button>Submit</button>
        </form>
    </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>

    <nav id="toc" cog-toc cog-toc-back></nav>
    <main>
        <section>
            <h2>Introduction</h2>
            <p>Some intro text...</p>
            <h3>Overview</h3>
            <p>Details here...</p>
        </section>
    </main>

    <section>
        <input type="text" cog-ghost placeholder="Focus me to dim surroundings" />
    </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>

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. | | cog-path | Displays a breadcrumb-style navigation trail based on visited pages or sections. Persists via session storage for 2 hours. | | cog-remind | Triggers a timed toast-style reminder after a specified delay. Use format like 10m:Don't forget to save! for custom messages. | | cog-toc | Generates an accessible table of contents from headings (h1–h6) within the next sibling element. Automatically assigns IDs and links. Optionally appends "Back to top" links after each section. | | cog-ghost | Dims and blurs the surrounding page content when the element receives focus. Automatically injects a full-screen overlay and styles, enhancing focus for form fields or interactive elements. | | cog-orient | Highlights the currently visible section in the viewport based on scroll position. Adds a focus class to <section> elements with cog-orient="true" as they enter view, helping users stay oriented within long pages. | | cog-delay | Adds an intentional delay before a button's action is triggered. When clicked, a visible countdown begins (default: 5 seconds) and a cancel button appears. If not canceled, the original action is executed. Supports calling a named function via cog-onclick="yourFunction". | | cog-break | Injects a "Take a Break" button that opens a fully accessible modal for a timed break (default: 5 minutes). The modal displays a countdown, a customizable title, message, and a cancel button. All text and duration can be overridden via cogBreakConfig. |

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
└── config/cog-read-config.js     # cog-read configuration
└── config/cog-break-config.js     # cog-break configuration

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;
      }
    `
  }
};

Use this to configure cog-break

// config/cog-break-config.js
window.cogBreakConfig = {
    buttonText: 'Take a Break',
    title: 'You are taking a break!',
    message: 'Relax for a while.',
    cancelButton: 'Cancel Break'
};

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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme