Notes, comments, and questions

content/body/accessible-text-svg.php

@@ -51,6 +51,7 @@
     This text complies with text spacing and text resizing requirements. If you use the
     text-spacing bookmarklet above, the text spaces out and doesn't get cut off.
   </p>
+  <!-- There is no bookmarklet above, even though it's mentioned in the previous paragraph -->
 
   <figure>
     <img src="images/accessible-text-svg/rollercoaster-screenshot__text-spacing.jpg"

content/body/code-quality.php

@@ -106,6 +106,7 @@
 </ol>
 
 <h3>Before we start</h3>
+<!-- Are these Babel changes actually needed? I don't see them being used in this project. -->
 
 <p>
   Our unit testing examples use ES6 modules. In order to support ES6 Modules in Jest, you need to do the following
@@ -159,6 +160,8 @@
   </template>
 
   <?php includeShowcode("test-code-walkthrough", "", "", "", true, 4)?>
+  <!-- TODO: The step 1 note ends in an incomplete sentence -->
+  <!-- Should step 2 and 3 only highlight the 'describe' or 'it' lines, instead of almost the whole file? -->
   <script type="application/json" id="test-code-walkthrough-props">
   {
     "replaceHtmlRules": {},
@@ -212,6 +215,8 @@
   </template>
 
   <?php includeShowcode("switch-test-code-walkthrough", "", "", "", true, 4)?>
+  <!-- TODO: The step 1 note ends in an incomplete sentence -->
+  <!-- Should step 2 and 3 only highlight the 'describe' or 'it' lines, instead of almost the whole file? -->
   <script type="application/json" id="switch-test-code-walkthrough-props">
   {
     "replaceHtmlRules": {},
@@ -270,6 +275,9 @@
   </template>
 
   <?php includeShowcode("test-code-walkthrough2", "", "", "", true, 4)?>
+  <!-- TODO: The step 1 note ends in an incomplete sentence -->
+  <!-- Should step 2 and 3 only highlight the 'describe' or 'it' lines, instead of almost the whole file? -->
+  <!-- Step #8 seems to highlight a lot more than the page.evaluate function. Should the RegEx be modified? -->
   <script type="application/json" id="test-code-walkthrough2-props">
   {
     "replaceHtmlRules": {},

content/body/combobox.php

@@ -9,7 +9,7 @@
   there. Because of this, I have spent a lot of time working on Enable's combobox implementation.
 </p>
 
-
+<!-- Example 3 is the first example on the page. This doesn't make sense. -->
 <h2>Example 3: Using HTML5 datalist</h2>
 
 <?php includeStats(array('doNot' => true, 'comment' => 'This does not work with assistive technologies in most web browsers.')) ?>
@@ -514,6 +514,7 @@
 
           <div role="listbox" id="aria-example-2__list" hidden>
             <div class="enable-combobox__group" role="group" aria-describedby="cat-1">
+            <!-- The "Communist States" heading has a permalink and is included in the TOC when it shouldn't be -->
               <h2 class="enable-combobox__group-header" role="presentation" id="cat-1">Communist States</h2>
 
               <div role="option">People's Republic of China</div>
@@ -529,6 +530,7 @@
             </div>
 
             <div class="enable-combobox__group" role="group" aria-describedby="cat-2">
+            <!-- The "Other States" heading has a permalink and is included in the TOC when it shouldn't be -->
               <h2 class="enable-combobox__group-header" role="presentation" id="cat-2">Other States</h2>
               <div role="option">Afghanistan</div>
               <div role="option">Albania</div>

content/body/exposing-style-info-to-screen-readers.php

@@ -112,6 +112,7 @@
   </code></pre>
 </div>
 
+<!-- It's unclear what this code walkthrough is of -->
 <?php includeShowcode("highlight-example", "", "", "", true, 2)?>
 <script type="application/json" id="highlight-example-props">
 {

content/body/focus-styling.php

@@ -1,6 +1,7 @@
 <p>
   Focus states are used by keyboard users to know what interactive element they can currently manipulate. They are
   usually styled with
+  <!-- TODO: missing remaining content -->
 
 <h2>Focus Styling For Keyboard Users Only</h2>
 

content/body/heading.php

@@ -20,6 +20,7 @@
 </p>
 
 <div class="enable-example">
+  <!-- TODO: replace the placeholder content -->
   Insert video here
 </div>
 

content/body/radiogroup.php

@@ -32,6 +32,7 @@
 
 
 <div id="example1" class="enable-example">
+    <!-- The "Set Alerts for your Account" heading has a permalink and is included in the TOC when it shouldn't be -->
   <h3 class="form-heading">Set Alerts for your Account</h3>
 
 
@@ -102,7 +103,8 @@
 </p>
 
 <div id="example1-styled" class="enable-example">
-  <div class="enable-radio">
+    <div class="enable-radio">
+      <!-- The "Set Alerts for your Account" heading has a permalink and is included in the TOC when it shouldn't be -->
     <h3 class="form-heading">Set Alerts for your Account</h3>
 
 
@@ -186,6 +188,7 @@
 </p>
 
 <div id="example2" class="enable-example">
+    <!-- The "Set Alerts for your Account" heading has a permalink and is included in the TOC when it shouldn't be -->
   <h3 class="form-heading">Set Alerts for your Account</h3>
 
 
@@ -287,6 +290,7 @@
 
 
 <div id="example4" class="enable-example">
+    <!-- The "Set Alerts for your Account" heading has a permalink and is included in the TOC when it shouldn't be -->
   <h3 class="form-heading">Set Alerts for your Account</h3>
   <div role="radiogroup" class="aria-form-group" aria-labelledby="html2-alert1">
     <p id="html2-alert1" class="legend">Send an alert when balance exceeds $ 3,000</p>
@@ -326,4 +330,4 @@
     "notes": "The radiogroup is like the <strong>fieldset</strong> tag. It should use the <strong>aria-labelledby</strong> to point to the element that labels the radiogroup (which acts as the legend tag)."
   }]
 }
-</script>
+</script>

content/body/skip-link.php

@@ -304,6 +304,7 @@
     the skip links will remain visible unless they are clicked.</strong>
   This seems like a reasonable tradeoff (and can arguably be better for accessibility).
 </p>
+<!-- I don't see the skip links remaining visible like mentioned as an issue. Are there only certain scenarios when this occurs? -->
 
 <div id="mobile-example" class="enable-example">
   <div class="enable-mobile-visible-on-focus__container enable-skip-link--begin">

content/body/tooltip.php

@@ -132,7 +132,7 @@
 </script>
 
 
-
+<!-- Should this be for the first example, instead of being under the second one? -->
 <?= includeNPMInstructions(
   'tooltip',
   array(),