docs(toggle): add v11 migration guidance (#9167)

.all-contributorsrc

@@ -203,7 +203,8 @@
       "avatar_url": "https://avatars2.githubusercontent.com/u/28265588?v=4",
       "profile": "https://janhassel.de/",
       "contributions": [
-        "code"
+        "code",
+        "doc"
       ]
     },
     {

README.md

@@ -104,7 +104,7 @@ check out our [Contributing Guide](/.github/CONTRIBUTING.md) and our
   <tr>
     <td align="center"><a href="https://github.com/johnbister"><img src="https://avatars3.githubusercontent.com/u/70543333?v=4?s=100" width="100px;" alt=""/><br /><sub><b>johnbister</b></sub></a><br /><a href="#design-johnbister" title="Design">🎨</a> <a href="https://github.com/carbon-design-system/carbon/pulls?q=is%3Apr+reviewed-by%3Ajohnbister" title="Reviewed Pull Requests">👀</a></td>
     <td align="center"><a href="https://github.com/dbrugger"><img src="https://avatars1.githubusercontent.com/u/10086178?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Dominik Brugger</b></sub></a><br /><a href="https://github.com/carbon-design-system/carbon/commits?author=dbrugger" title="Code">💻</a> <a href="#maintenance-dbrugger" title="Maintenance">🚧</a></td>
-    <td align="center"><a href="https://janhassel.de/"><img src="https://avatars2.githubusercontent.com/u/28265588?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Jan Hassel</b></sub></a><br /><a href="https://github.com/carbon-design-system/carbon/commits?author=janhassel" title="Code">💻</a></td>
+    <td align="center"><a href="https://janhassel.de/"><img src="https://avatars2.githubusercontent.com/u/28265588?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Jan Hassel</b></sub></a><br /><a href="https://github.com/carbon-design-system/carbon/commits?author=janhassel" title="Code">💻</a> <a href="https://github.com/carbon-design-system/carbon/commits?author=janhassel" title="Documentation">📖</a></td>
     <td align="center"><a href="https://github.com/AlexanderLyon"><img src="https://avatars0.githubusercontent.com/u/17458641?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Alexander Lyon</b></sub></a><br /><a href="https://github.com/carbon-design-system/carbon/commits?author=AlexanderLyon" title="Code">💻</a></td>
     <td align="center"><a href="https://github.com/rzhekova"><img src="https://avatars2.githubusercontent.com/u/35401262?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Rosie Z</b></sub></a><br /><a href="https://github.com/carbon-design-system/carbon/commits?author=rzhekova" title="Code">💻</a></td>
     <td align="center"><a href="http://abdul-sen.github.io/portfolio"><img src="https://avatars2.githubusercontent.com/u/38502132?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Abdul Rehman</b></sub></a><br /><a href="https://github.com/carbon-design-system/carbon/commits?author=Abdul-Sen" title="Code">💻</a></td>

packages/react/src/components/Toggle/migrate-to-11.x.md

@@ -0,0 +1,52 @@
+# Toggle
+
+## Markup
+
+| Change                                                                                                                       | Rationale                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| :--------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The underlying element was changed from a checkbox (`<input type="checkbox">`) to a switch button (`<button role="switch">`) | <ul> <li>The switch button better resembles the toggle component from an accessibility standpoint: _"A type of checkbox that represents on/off values, as opposed to checked/unchecked values" (https://www.w3.org/TR/2017/REC-wai-aria-1.1-20171214/#switch)_</li> <li>A toggle cannot present a mixed state which a checkbox can</li> <li>A switch button natively supports being toggled on <kbd>Enter</kbd></li> </ul> |
+| `props['aria-label']` is no longer required                                                                                  | The new markup ensures `props.labelText` will always be available to screen readers without the use of `aria-label`                                                                                                                                                                                                                                                                                                        |
+
+### New markup
+
+```html
+<div class="bx--toggle">
+  <button
+    id="toggle-id"
+    class="bx--toggle__button"
+    role="switch"
+    type="button"
+    aria-checked="true"
+  ></button>
+  <label class="bx--toggle__label" for="toggle-id">
+    <span class="bx--toggle__label-text bx--visually-hidden">Toggle label</span>
+    <div class="bx--toggle__appearance">
+      <span class="bx--toggle__text" aria-hidden="true">On</span>
+    </div>
+  </label>
+</div>
+```
+
+### Old markup
+
+```html
+<div class="bx--form-item">
+  <input type="checkbox" id="toggle-id" class="bx--toggle-input" checked />
+  <label class="bx--toggle-input__label" for="toggle-id">
+    Toggle label
+    <span class="bx--toggle__switch">
+      <span class="bx--toggle__text--off" aria-hidden="true">Off</span>
+      <span class="bx--toggle__text--on" aria-hidden="true">On</span>
+    </span>
+  </label>
+</div>
+```
+
+## Props
+
+| v7           | v11         | Note                                                                                         |
+| :----------- | :---------- | :------------------------------------------------------------------------------------------- |
+| `aria-label` | -           | Removed. No longer required. If still passed, it will be emitted on the `<button>` element.  |
+| -            | `hideLabel` | New. Visually hides the label above the toggle while keeping it available to screen readers. |
+| `onChange`   | -           | Removed. Not available on `<button>` elements.                                               |
+| -            | `onClick`   | New. To substitute previous `props.onChange`                                                 |