docs(button,iconbutton): add docs for soft-disabled attribute

Fixes #5672

PiperOrigin-RevId: 651409230

Author: zelliott

docs/components/button.md

@@ -236,6 +236,28 @@ attribute to buttons whose labels need a more descriptive label.
 <md-elevated-button aria-label="Add a new contact">Add</md-elevated-button>
 ```
 
+### Focusable and disabled
+
+By default, disabled buttons are not focusable with the keyboard, while
+"soft-disabled" buttons are. Some use cases encourage focusability of disabled
+toolbar items to increase their discoverability.
+
+See the
+[ARIA guidelines on focusability of disabled controls](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls)<!-- {.external} -->
+for guidance on when this is recommended.
+
+```html
+<div role="toolbar">
+  <md-text-button>Copy</md-text-button>
+  <md-text-button>Cut</md-text-button>
+  <!--
+    This button is disabled but kept focusable to improve its discoverability
+    in the toolbar.
+  -->
+  <md-text-button soft-disabled>Paste</md-text-button>
+</div>
+```
+
 ## Elevated button
 
 <!-- go/md-elevated-button -->
@@ -703,7 +725,6 @@ Token                               | Default value
 
 ## API
 
-
 ### MdElevatedButton <code>&lt;md-elevated-button&gt;</code>
 
 #### Properties
@@ -713,6 +734,7 @@ Token                               | Default value
 | Property | Attribute | Type | Default | Description |
 | --- | --- | --- | --- | --- |
 | `disabled` | `disabled` | `boolean` | `false` | Whether or not the button is disabled. |
+| `softDisabled` | `soft-disabled` | `boolean` | `false` | Whether the button is "soft-disabled" (disabled but still focusable). |
 | `href` | `href` | `string` | `''` | The URL that the link button points to. |
 | `target` | `target` | `string` | `''` | Where to display the linked `href` URL for a link button. Common options include `_blank` to open in a new tab. |
 | `trailingIcon` | `trailing-icon` | `boolean` | `false` | Whether to render the icon at the inline end of the label rather than the inline start.<br>_Note:_ Link buttons cannot have trailing icons. |

docs/components/icon-button.md

@@ -196,6 +196,34 @@ more descriptive label when selected.
 </md-icon-button>
 ```
 
+### Focusable and disabled
+
+By default, disabled icon buttons are not focusable with the keyboard, while
+"soft-disabled" icon buttons are. Some use cases encourage focusability of
+disabled toolbar items to increase their discoverability.
+
+See the
+[ARIA guidelines on focusability of disabled controls](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_disabled_controls)<!-- {.external} -->
+for guidance on when this is recommended.
+
+```html
+<div role="toolbar">
+  <md-icon-button aria-label="Copy">
+    <md-icon>copy</md-icon>
+  </md-icon-button>
+  <md-icon-button aria-label="Cut">
+    <md-icon>cut</md-icon>
+  </md-icon-button>
+  <!--
+    This icon button is disabled but kept focusable to improve its
+    discoverability in the toolbar.
+  -->
+  <md-icon-button aria-label="Paste" soft-disabled>
+    <md-icon>paste</md-icon>
+  </md-icon-button>
+</div>
+```
+
 ## Icon Button
 
 Standard icon buttons do not have a background or outline, and have the lowest
@@ -319,7 +347,7 @@ Token                                | Default value
 ### Filled Icon Button tokens
 
 Token                                              | Default value
--------------------------------------------------- | ------------------------
+-------------------------------------------------- | -------------
 `--md-filled-icon-button-selected-container-color` | `--md-sys-color-primary`
 `--md-filled-icon-button-container-shape`          | `--md-sys-shape-corner-full`
 `--md-filled-icon-button-container-width`          | `40px`
@@ -391,7 +419,7 @@ Token                                                    | Default value
 ### Outlined Icon Button tokens
 
 Token                                        | Default value
--------------------------------------------- | ------------------------
+-------------------------------------------- | ----------------------------
 `--md-outlined-icon-button-outline-color`    | `--md-sys-color-outline`
 `--md-outlined-icon-button-outline-width`    | `1px`
 `--md-outlined-icon-button-container-shape`  | `--md-sys-shape-corner-full`
@@ -428,7 +456,6 @@ Token                                        | Default value
 
 ## API
 
-
 ### MdIconButton <code>&lt;md-icon-button&gt;</code>
 
 #### Properties
@@ -472,6 +499,7 @@ Token                                        | Default value
 | Property | Attribute | Type | Default | Description |
 | --- | --- | --- | --- | --- |
 | `disabled` | `disabled` | `boolean` | `false` | Disables the icon button and makes it non-interactive. |
+| `softDisabled` | `soft-disabled` | `boolean` | `false` | "Soft-disables" the icon button (disabled but still focusable). |
 | `flipIconInRtl` | `flip-icon-in-rtl` | `boolean` | `false` | Flips the icon if it is in an RTL context at startup. |
 | `href` | `href` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `href` resource attribute. |
 | `target` | `target` | `string` | `''` | Sets the underlying `HTMLAnchorElement`'s `target` attribute. |