Skip to content

ACCESSIBILITY_IMPROVEMENTS.md

Latest commit

 

History

History
273 lines (206 loc) · 8.87 KB

ACCESSIBILITY_IMPROVEMENTS.md

File metadata and controls

273 lines (206 loc) · 8.87 KB

PyPI Download Chart Accessibility Improvements

Overview

This document describes the comprehensive accessibility improvements made to the PyPI Download Charts component to address colorblind accessibility issues and verify data authenticity.

Issue 1: Data Verification - RESOLVED

Investigation Results

The PyPI download data is 100% authentic and sourced directly from pypistats.org API.

Data Source Verification:

  • API Endpoint: https://pypistats.org/api/packages/{package}/overall
  • Mirror Data: Uses category: 'with_mirrors' for accurate worldwide download counts
  • Proxy Implementation: /api/pypistats proxies requests to avoid CORS issues
  • No Mock Data: All data comes from live PyPI API responses

Package Discovery:

  • Uses /api/discover-packages to dynamically discover all openadapt-* packages
  • Validates each package exists on PyPI before fetching stats
  • Fallback list only used if PyPI is unreachable
  • Cache: 24-hour client-side cache for performance

Chronological Order:

  • openadapt (main package): First published 2023-08-10
  • openadapt-ml: First published 2025-12-16
  • The chart correctly shows openadapt as the earliest package

Example API Response:

{
  "data": [
    {"category": "with_mirrors", "date": "2026-01-17", "downloads": 420},
    {"category": "with_mirrors", "date": "2026-01-15", "downloads": 5}
  ],
  "package": "openadapt",
  "type": "overall_downloads"
}

Issue 2: Colorblind Accessibility - IMPLEMENTED

Problem

The "By Package" chart was difficult to use for colorblind users because:

  • Lines were only distinguished by color
  • Similar colors (red/green) are indistinguishable to many colorblind users
  • No way to identify which line represented which package without relying on color

Solution Implemented

We implemented a multi-layered accessibility approach that does not rely solely on color:

1. Colorblind-Safe Color Palette

Implemented the Tol Bright color scheme, scientifically designed for all types of color vision deficiency:

const TOL_BRIGHT_COLORS = [
    '#4477AA', // Blue
    '#EE6677', // Red
    '#228833', // Green
    '#CCBB44', // Yellow
    '#66CCEE', // Cyan
    '#AA3377', // Purple
    '#BBBBBB', // Grey
    '#EE7733', // Orange
];

Benefits:

  • Distinguishable for protanopia (red-blind)
  • Distinguishable for deuteranopia (green-blind)
  • Distinguishable for tritanopia (blue-blind)
  • Distinguishable for achromatopsia (total colorblindness)
  • Avoids problematic red-green combinations

Reference: https://personal.sron.nl/~paultol/data/colourschemes.pdf

2. Line Patterns (Dash Styles)

Each package uses a unique dash pattern:

Package Pattern Description
openadapt [] Solid line (3px)
openadapt-ml [10, 5] Dashed
openadapt-capture [2, 3] Dotted
openadapt-evals [15, 5, 5, 5] Dash-dot
openadapt-viewer [20, 5] Long dash
openadapt-grounding [5, 5, 1, 5] Dash-dot-dot
openadapt-retrieval [8, 4, 2, 4] Mixed pattern
openadapt-privacy [12, 3] Medium dash

3. Line Widths

Lines vary between 2-3px for additional differentiation:

  • Primary package (openadapt): 3px
  • Other packages: 2-2.5px

4. Interactive Legend

The legend now includes:

  • Click to toggle: Click any legend item to show/hide that package line
  • Visual patterns: Legend boxes show the same line pattern as the chart
  • Hover cursor: Pointer cursor indicates interactivity
  • Hidden state: Grayed out when a package is hidden

5. Enhanced Tooltips

Tooltips now display:

  • Date in the title (bold, larger font)
  • Package name with exact download count
  • Color indicators matching the line color and pattern
  • Total downloads across all packages (footer)
  • Version information for the openadapt main package (if available)

6. Hover Highlighting

When hovering over any data point:

  • The associated package line is emphasized
  • Other lines fade to 20% opacity
  • Makes it easy to trace which line you're examining
  • Updates without animation for smooth interaction

Package-Specific Configuration

Each package now has a complete accessibility configuration:

const packageColors = {
    'openadapt': {
        border: '#4477AA',              // Tol bright blue
        background: '#4477AA33',         // 20% opacity
        borderDash: [],                  // Solid
        borderWidth: 3,                  // Thickest
    },
    // ... etc for other packages
};

Testing Instructions

1. Visual Testing with Colorblind Simulators

Chrome DevTools Method:

  1. Open Chrome DevTools (F12)
  2. Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
  3. Type "Rendering" and select "Show Rendering"
  4. Scroll to "Emulate vision deficiencies"
  5. Test each mode:
    • Protanopia (no red)
    • Deuteranopia (no green)
    • Tritanopia (no blue)
    • Achromatopsia (no color)

Firefox Method:

  1. Open Developer Tools (F12)
  2. Click the Accessibility tab
  3. Click "Simulate" dropdown
  4. Test each vision deficiency mode

2. Functional Testing

Test these interactions on the "By Package" chart:

  • Legend Click: Click each package in the legend to toggle visibility
  • Hover Highlighting: Hover over lines - verify other lines fade out
  • Tooltip Display: Hover over data points - verify tooltips show package names
  • Line Patterns: Verify each line has a visually distinct pattern
  • Color Distinction: Verify colors are distinguishable in colorblind modes

3. Accessibility Testing Checklist

  • Can identify all packages without relying on color?
  • Can distinguish lines using patterns alone?
  • Does hover highlighting make lines clearly identifiable?
  • Are tooltips informative and accessible?
  • Can toggle specific packages via legend?
  • Do patterns appear in legend boxes?

4. Cross-Browser Testing

Test on:

  • Chrome/Chromium
  • Firefox
  • Safari
  • Edge

5. Responsive Testing

Test at different screen sizes:

  • Desktop (1920px+)
  • Laptop (1366px)
  • Tablet (768px)
  • Mobile (375px)

Implementation Details

Files Modified

  1. /components/PyPIDownloadChart.js - Main chart component
    • Added Tol bright color palette
    • Implemented line patterns and widths
    • Enhanced tooltip callbacks
    • Added interactive legend with click handlers
    • Implemented hover highlighting with opacity changes

Dependencies

No new dependencies required. Uses existing Chart.js features:

  • borderDash for line patterns
  • borderWidth for line thickness
  • onClick/onHover for legend interactivity
  • onHover at chart level for highlighting
  • Tooltip callbacks for enhanced content

Performance Considerations

  • Hover updates use chart.update('none') to avoid animation lag
  • Legend pattern generation is efficient (simple array mapping)
  • Color palette is constant (no runtime computation)
  • Line patterns have minimal rendering overhead

Before vs After

Before

  • Only color distinguished packages
  • Red/green combination problematic
  • No hover highlighting
  • Basic legend (no interactivity)
  • Simple tooltips

After

  • Color + Pattern + Width distinguish packages
  • Colorblind-safe palette (Tol bright)
  • Hover highlighting with opacity fading
  • Interactive legend (click to toggle, shows patterns)
  • Enhanced tooltips (package names, totals, version info)

Accessibility Standards Met

✅ WCAG 2.1 Level AA - Use of Color (1.4.1)

  • Does not rely on color alone for information

✅ WCAG 2.1 Level AA - Visual Presentation (1.4.8)

  • Enhanced contrast and visual differentiation

✅ WCAG 2.1 Level AA - Non-text Contrast (1.4.11)

  • Line patterns provide non-color distinction

References

  1. Tol Bright Color Scheme: https://personal.sron.nl/~paultol/data/colourschemes.pdf
  2. Chart.js Line Styling: https://www.chartjs.org/docs/latest/charts/line.html
  3. WCAG 2.1 Guidelines: https://www.w3.org/WAI/WCAG21/quickref/
  4. PyPI Stats API: https://pypistats.org/api/

Future Enhancements

Potential future improvements:

  1. End-of-line labels: Add package names at the end of each line (requires chartjs-plugin-datalabels)
  2. Pattern legend: Add a visual guide showing all patterns
  3. High contrast mode: Additional theme for users with very low vision
  4. Keyboard navigation: Arrow keys to navigate between data points
  5. Screen reader improvements: Add ARIA labels for better screen reader support

Conclusion

These accessibility improvements ensure that the PyPI download charts are usable by all users, regardless of color vision ability. The multi-layered approach (color + pattern + width + interactivity) provides redundant visual cues so no single factor is required for chart comprehension.

The data verification confirms that all statistics are authentic and sourced directly from PyPI's official APIs.