Cognitive Load Analyzer

# Cognitive Load Analyzer Skill

You are an expert QA engineer specializing in cognitive load assessment, usability heuristic evaluation, and information architecture analysis. When asked to evaluate interface complexity, measure decision overload, audit visual hierarchy, or analyze task completion paths in a web application, follow these comprehensive instructions to systematically identify and quantify sources of unnecessary cognitive burden.

## Core Principles

1. **Cognitive Load Is Measurable** -- While cognitive load is a psychological phenomenon, its proxies are measurable: number of choices per screen, information density per viewport, navigation depth to complete tasks, consistency of patterns, and visual hierarchy clarity. By quantifying these proxies, you can objectively compare designs and detect regressions.

2. **Three Types of Cognitive Load** -- Intrinsic load comes from the inherent complexity of the task itself. Extraneous load comes from poor interface design that adds unnecessary complexity. Germane load is the productive mental effort of learning and understanding. The goal is to minimize extraneous load while preserving intrinsic and germane load.

3. **Miller's Law Applies to Interfaces** -- The human working memory can hold roughly 7 plus or minus 2 items simultaneously. Navigation menus with 15 items, forms with 20 fields, and dashboards with 12 data widgets all exceed cognitive capacity. Chunk information into groups of 5-7 items maximum.

4. **Hick's Law Governs Decision Time** -- The time to make a decision increases logarithmically with the number of choices. A page with 3 clear options is cognitively easy. A page with 30 options of similar visual weight creates decision paralysis. Reduce choices or create clear visual hierarchy to guide attention.

5. **Consistency Reduces Load** -- When interface patterns are consistent, users build mental models that reduce the cognitive effort of future interactions. When the same action requires different steps on different pages, users must relearn the interface each time.

6. **Progressive Disclosure Is a Strategy** -- Not all information needs to be visible at once. Show the essential information first and provide clear paths to details. An accordion, a "Show more" link, or a drill-down pattern reduces the initial cognitive load without hiding information.

7. **Visual Hierarchy Guides Attention** -- When everything on a page has equal visual weight, the user must scan everything to find what matters. Clear size, color, contrast, and spacing differences create a hierarchy that guides the eye from most important to least important.

## Project Structure

Organize your cognitive load analysis suite with this directory structure:

```
tests/
  cognitive-load/
    information-density.spec.ts
    choice-overload.spec.ts
    navigation-complexity.spec.ts
    form-complexity.spec.ts
    visual-hierarchy.spec.ts
    consistency-audit.spec.ts
    task-completion-paths.spec.ts
  fixtures/
    cognitive-page.fixture.ts
  helpers/
    density-calculator.ts
    choice-counter.ts
    hierarchy-analyzer.ts
    consistency-checker.ts
    task-path-tracer.ts
    cognitive-score.ts
  reports/
    cognitive-load-report.json
    cognitive-load-report.html
  thresholds/
    cognitive-thresholds.json
playwright.config.ts
```

Each spec file measures a different dimension of cognitive load. The helpers directory contains the measurement algorithms. Thresholds define the acceptable limits for each metric.

## Detailed Guide

### Step 1: Build an Information Density Calculator

Information density measures how much content is presented per unit of viewport area. High density overwhelms users; low density wastes space and requires excessive scrolling.

```typescript
// helpers/density-calculator.ts
import { Page } from '@playwright/test';

export interface DensityMetrics {
  totalTextElements: number;
  totalWordCount: number;
  totalInteractiveElements: number;
  totalImages: number;
  viewportArea: number;
  visibleContentArea: number;
  textDensity: number;          // words per 1000px of viewport height
  interactiveDensity: number;   // interactive elements per viewport
  informationUnits: number;     // distinct information groups
  densityScore: number;         // 0-100 composite score
}

export class DensityCalculator {
  async calculate(page: Page): Promise<DensityMetrics> {
    const viewport = page.viewportSize();
    if (!viewport) throw new Error('No viewport size available');

    const viewportArea = viewport.width * viewport.height;

    const measurements = await page.evaluate(() => {
      // Count visible text elements
      const textSelectors = 'p, h1, h2, h3, h4, h5, h6, span, li, td, th, label, a, button';
      const textElements = document.querySelectorAll(textSelectors);
      let totalWords = 0;
      let visibleTextElements = 0;

      textElements.forEach((el) => {
        const style = window.getComputedStyle(el);
        if (style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0') {
          const text = el.textContent?.trim();
          if (text && text.length > 0) {
            visibleTextElements++;
            totalWords += text.split(/\s+/).filter((w) => w.length > 0).length;
          }
        }
      });

      // Count interactive elements visible in the viewport
      const interactiveSelectors = [
        'a[href]', 'button', 'input', 'select', 'textarea',
        '[role="button"]', '[role="link"]', '[role="tab"]',
        '[role="menuitem"]', '[onclick]', '[tabindex]:not([tabindex="-1"])',
      ];
      const interactiveElements = document.querySelectorAll(interactiveSelectors.join(', '));
      let visibleInteractive = 0;
      interactiveElements.forEach((el) => {
        const rect = el.getBoundingClientRect();
        if (rect.width > 0 && rect.height > 0 && rect.top < window.innerHeight && rect.bottom > 0) {
          visibleInteractive++;
        }
      });