Skip to main content

CogJS - Cognitive-Oriented Web Accessibility Toolkit

cog-background

cog-background is a declarative attribute used to apply cognitive-friendly themes to elements on a page. It is part of CogJS, a lightweight JavaScript library focused on cognitive and neurodivergent accessibility enhancements.

What It Does

The attribute enables accessible theming without additional CSS. Developers can use predefined or custom themes to reduce visual stress and enhance readability, especially for users with dyslexia, sensory sensitivity, or ADHD.

Theme Configuration

Configure themes in cog-theme.js before loading the script. You can define custom background and foreground color combinations. 

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'],
    foreground: ['p', 'h1', 'h2', 'li', 'a']
  }
};

Enabling in HTML

To enable a theme, add cog-background="theme-name" to the root element or any section of your page. 

<section cog-background="dark-mode">
  <h2>Dark Themed Section</h2>
  <p>This area uses a dark background with light foreground for improved contrast.</p>
</section>

Accessibility Considerations

  • Improves Readability: Helpful for users with dyslexia, Irlen Syndrome, or sensory fatigue.
  • Reduces Visual Noise: Muted background themes reduce distraction.
  • Declarative & Flexible: Works on any HTML element without additional CSS.
  • Supports System Preferences: Can be configured to respect OS-level dark/light mode.

Testing cog-background

// Test Checklist
// - Apply cog-background to a <body> or <section>
// - Verify correct background and foreground colors appear
// - Check legibility in different light environments
// - Ensure user settings (if any) are respected

Best Practices for cog-background

  • Use Semantic Themes: Choose color combinations that are WCAG AA/AAA compliant where possible.
  • Provide Options: Let users switch between themes if feasible.
  • Apply Intelligently: Use per-section overrides only where appropriate.
  • Combine Thoughtfully: Works well with cog-read and cog-toggle-content for layered support.
  • Always Test: Manually inspect and use tools to validate theme contrast ratios.