Merge pull request #2 from DS-100/a11y-fixes

Fix Accessibility Violations

Author: pancakereport

.github/workflows/a11y.yml

@@ -6,53 +6,25 @@ on:
 
 env:
   PRODUCTION_URL: "https://ds100.org/debugging-guide/"
-  # must match the end of PRODUCTION_URL
-  # leave blank if at root
   SITE_SUBDIR: "debugging-guide"
 
 jobs:
   axe-audit:
     runs-on: ubuntu-latest
 
     steps:
-      # 1. Checkout Code
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      # 2. Setup Quarto with TinyTex
-      - name: Set up Quarto
-        uses: quarto-dev/quarto-actions/setup@v2
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          tinytex: true
-
-      # 3. Setup Node.js (for Axe and http-server)
+      # Setup Node.js and install Axe and http-server
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
           node-version: '20'
-
-      # 4. Setup Python
-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: '3.11.9' 
-          cache: 'pip' 
-
-      # 5. Install Python dependencies
-      - name: Install Python dependencies
-        run: pip install -r requirements.txt
-      
-      # 6. Render the Site
-      - name: Render Quarto Site
-        run: quarto render
-
-      # 7. Install Tools
       - name: Install Axe and Server
         run: npm install -g @axe-core/cli http-server
 
-      # 8. Start Local Server (Background Process)
+      # Start Local Server 
       - name: Start Local Server
         run: |
           # Mimic the production path structure exactly with
@@ -65,7 +37,7 @@ jobs:
           
           sleep 5
 
-      # 9. Run Axe Scan
+      # Run Axe Scan
       - name: Run Accessibility Scan
         id: axe-scan
         run: |
@@ -86,7 +58,7 @@ jobs:
             --save axe-report.json \
             --exit
 
-      # 10. Upload Report (Runs even if previous step fails)
+      # Upload Report even if previous step fails
       - name: Upload Accessibility Report
         if: always() 
         uses: actions/upload-artifact@v4

README.md

@@ -1,6 +1,6 @@
 # Debugging Guide
 
-[![Accessibility Checks](https://github.com/DS-100/debugging-guide/actions/workflows/a11y.yml/badge.svg)](https://github.com/DS-100/debugging-guide/actions/workflows/a11y.yml)
+[![pages-build-deployment](https://github.com/DS-100/debugging-guide/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/DS-100/debugging-guide/actions/workflows/pages/pages-build-deployment) [![Accessibility Checks](https://github.com/DS-100/debugging-guide/actions/workflows/a11y.yml/badge.svg)](https://github.com/DS-100/debugging-guide/actions/workflows/a11y.yml)
 
 Website link: https://ds100.org/debugging-guide/
 
@@ -42,7 +42,7 @@ pip3 install -r requirements.txt # will take a while
 ipython kernel install --user
 ```
 
-If you get an `error: externally-managed-environment` on the third line, run `pip3 install -r requirements.txt --break-system-packages`
+If you get an `error: externally-managed-environment` on the third line, run `pip3 install -r requirements.txt --break-system-packages`. You may also run into issues if you're running on Apple silicon. I fixed this by running `conda install -c conda-forge scikit-learn==1.2.2 scikit-image==0.25.2` before `pip3 install -r requirements.txt`.
 
 Remember to always activate the right environment before running anything with `conda activate data100quarto`.
 
@@ -95,9 +95,11 @@ A pdf view of how this notebook renders in Quarto can be found [here](https://dr
 
 To give you the most control when inserting images, we use html with the following format to center images/figs and control their size: 
 
-```<center><img src = "IMAGE_NAME" width = "IMAGE_WIDTH_IN_PIXELS"></img></a></center>```
+```<center><img src = "IMAGE_NAME" width = "IMAGE_WIDTH_IN_PIXELS" alt="alt text here"></img></a></center>```
 
-For example, `<center><img src = "images/updated_basic.png" width = "700"></img></a></center>`.
+For example, `<center><img src = "images/updated_basic.png" width = "700" alt="description of image"></img></a></center>`.
+
+In some instances, the images may be completely described in the text of the page. In these cases, you may leave the alt text blank i.e. `alt=""`. BUT THE ALT TEXT MUST STILL BE INCLUDED.
 
 
 ## Generating Output + Rendering Website

_quarto.yml

@@ -1,44 +1,48 @@
 project:
-  type: book
+  type: website
   output-dir: docs
 
-book:
+website:
   site-url: "https://ds100.org/debugging-guide/"
+  page-footer: 
+    center:
+      - text: Accessibility
+        href: "https://dap.berkeley.edu/get-help/report-web-accessibility-issue"
+      - text: Nondiscrimination
+        href: "https://ophd.berkeley.edu/policies-and-procedures/nondiscrimination-policy-statement"
   favicon: data100_logo.png
   title: "Data 100 Debugging Guide"
   image: data100_logo.png
-  author: ["Yash Dave", "Lillian Weng", "Wesley Zheng", "Emrie Loh"]
   repo-url: https://github.com/DS-100/debugging-guide
   search:
     location: sidebar
     type: textbox
-  chapters:
-    - index.md
-    - jupyter101/jupyter101.md
-    - jupyter_datahub/jupyter_datahub.md
-    - autograder_gradescope/autograder_gradescope.md
-    - pandas/pandas.md
-    - regex/regex.md
-    - visualizations/visualizations.md
-    - projA1/projA1.md
-    - projA2/projA2.md
-    - sql/sql.md
-
   sidebar:
     logo: "data100_logo.png"
+    style: "docked"
+    title: "Data 100 Debugging Guide"
+    logo-alt: "Data 100 logo"
+    tools:
+      - icon: github
+        href: https://github.com/DS-100/debugging-guide
+    contents:
+      - index.md
+      - jupyter101/jupyter101.md
+      - jupyter_datahub/jupyter_datahub.md
+      - autograder_gradescope/autograder_gradescope.md
+      - pandas/pandas.md
+      - regex/regex.md
+      - visualizations/visualizations.md
+      - projA1/projA1.md
+      - projA2/projA2.md
+      - sql/sql.md
 format:
   html:
-    theme: cosmo
+    theme: cosmos
     toc: true
     toc-depth: 5
     toc-expand: 3 # depth to expand index
     callout-icon: false
     number-sections: false
-  pdf: default
-#   navbar:
-#     search: false
-#     right:
-#       - icon: github
-#         href: https://github.com/
-#         aria-label: GitHub
-#       - icon: arrows-fullscreen
+    include-after-body: 
+      - a11y-fixes.html

a11y-fixes.html

@@ -0,0 +1,36 @@
+<script>
+    document.addEventListener("DOMContentLoaded", function() {
+    // 1. Select the specific parent div within the callout header that has the 
+    //    collapse attributes (data-bs-toggle).
+    var calloutToggles = document.querySelectorAll(
+        '.callout-header[data-bs-toggle="collapse"]'
+    );
+
+    calloutToggles.forEach(function(toggle) {
+        // 2. Force the ARIA role to be 'button'
+        // This is crucial because a 'div' is not allowed to use aria-expanded.
+        toggle.setAttribute('role', 'button');
+        
+        // 3. Ensure it is keyboard-focusable (critical accessibility fix)
+        if (toggle.getAttribute('tabindex') === null) {
+             toggle.setAttribute('tabindex', '0');
+        }
+    });
+
+    // Scrollable Region Accessibility Fix:
+    // Target ALL <pre> elements, as they are the source of the scrollable-region-focusable errors.
+    var scrollableRegions = document.querySelectorAll('pre'); 
+
+    scrollableRegions.forEach(function(region) {
+        // Check if the element has horizontal overflow (is scrollable).
+        const hasScrollbar = region.scrollWidth > region.clientWidth || region.scrollHeight > region.clientHeight;
+
+        if (hasScrollbar) {
+            // If it is scrollable AND it doesn't already have tabindex="0" (or a different value)
+            if (region.getAttribute('tabindex') === null || region.getAttribute('tabindex') === undefined) {
+                    region.setAttribute('tabindex', '0');
+            }
+        }
+    });
+});
+</script>

autograder_gradescope/autograder_gradescope.md

@@ -2,14 +2,8 @@
 title: Autograder and Gradescope / Pensieve
 format:
   html:
-    toc: true
-    toc-depth: 5
     toc-location: right
     code-fold: false
-    theme:
-      - cosmo
-      - cerulean
-    callout-icon: false
 jupyter:
   jupytext:
     text_representation:
@@ -34,16 +28,16 @@ jupyter:
 
 When you pass a test, you'll see a nice message and a cute emoji!
 
-<center><img src = "passing_autograder.png" width = "200"></img></a></center>
+<center><img src = "passing_autograder.png" width = "200" alt="Screenshot of a grader cell for question q2a with cell ouput 'q2a passed'"></img></a></center>
 
 When you don't, however, the message can be a little confusing.
 
-<center><img src = "autograder_error.png" width = "600"></img></a></center>
+<center><img src = "autograder_error.png" width = "600" alt="Example of a cell output for a failing autograder test showing what test failed, what the code that was evaluated was, the expected output, and an error that was raised during the course of the test."></img></a></center>
 <br>
 
 The best course of action is to find the test case that failed and use that as a starting point to debug your code.
 
-<center><img src = "autograder_error_annot.png" width = "700"></img></a></center>
+<center><img src = "autograder_error_annot.png" width = "700" alt="An annotated version of the previous image which includes the note 'The most useful error message is usually at the bottom'"></img></a></center>
 
 In the example above, we see that the test case in green, `max_swing in set(bus['name'])`, is not passing. The actual output (in blue) is often hard to parse, so the best course of action is to:
 
@@ -100,11 +94,11 @@ This can happen if you import external packages when you are not instructed to d
 
 If your Gradescope submission page has been stuck running on this page for a while:
 
-<center><img src = "gradescope_loading.png" width = "350"></img></a></center>
+<center><img src = "gradescope_loading.png" width = "350" alt="Autograder Results. The autograder hasn't finish running yet."></img></a></center>
 
 or if it times out:
 
-<center><img src = "gradescope_timeout.png" width = "650"></img></a></center>
+<center><img src = "gradescope_timeout.png" width = "650" alt="Autograder Results. In a red box 'The autograder failed to respond in the expected amount of time. If the autograder continues to fail, contact your course staff for help in debugging this issue. Make sure to include a link to this page so they can help you most effectively.'"></img></a></center>
 
 it means that the Gradescope autograder failed to execute in the expected amount of time. TThis could be due to an inefficiency in your code or an issue on Gradescope's end, so we recommend resubmitting and allowing the autograder to rerun. If the issue persists after a few attempts, you may need to investigate your code for inefficiencies.