diff --git a/docs/assets/images/badge-do-1.png b/docs/assets/images/badge-do-1.png new file mode 100644 index 00000000..77cdbf13 Binary files /dev/null and b/docs/assets/images/badge-do-1.png differ diff --git a/docs/assets/images/badge-do-2.png b/docs/assets/images/badge-do-2.png new file mode 100644 index 00000000..cfc0a403 Binary files /dev/null and b/docs/assets/images/badge-do-2.png differ diff --git a/docs/assets/images/badge-do-3.png b/docs/assets/images/badge-do-3.png new file mode 100644 index 00000000..2299ce8b Binary files /dev/null and b/docs/assets/images/badge-do-3.png differ diff --git a/docs/assets/images/badge-dont-1.png b/docs/assets/images/badge-dont-1.png new file mode 100644 index 00000000..1ac1c5cc Binary files /dev/null and b/docs/assets/images/badge-dont-1.png differ diff --git a/docs/assets/images/badge-dont-2.png b/docs/assets/images/badge-dont-2.png new file mode 100644 index 00000000..559fab63 Binary files /dev/null and b/docs/assets/images/badge-dont-2.png differ diff --git a/docs/assets/images/badge-dont-3.png b/docs/assets/images/badge-dont-3.png new file mode 100644 index 00000000..aeb84b17 Binary files /dev/null and b/docs/assets/images/badge-dont-3.png differ diff --git a/docs/assets/images/badge-hero.png b/docs/assets/images/badge-hero.png new file mode 100644 index 00000000..4c75e0ac Binary files /dev/null and b/docs/assets/images/badge-hero.png differ diff --git a/docs/assets/images/button-do-1.png b/docs/assets/images/button-do-1.png new file mode 100644 index 00000000..811401ed Binary files /dev/null and b/docs/assets/images/button-do-1.png differ diff --git a/docs/assets/images/button-do-2.png b/docs/assets/images/button-do-2.png new file mode 100644 index 00000000..a0028b36 Binary files /dev/null and b/docs/assets/images/button-do-2.png differ diff --git a/docs/assets/images/button-do-3.png b/docs/assets/images/button-do-3.png new file mode 100644 index 00000000..4e6b4270 Binary files /dev/null and b/docs/assets/images/button-do-3.png differ diff --git a/docs/assets/images/button-do-4.png b/docs/assets/images/button-do-4.png new file mode 100644 index 00000000..a7eb5d77 Binary files /dev/null and b/docs/assets/images/button-do-4.png differ diff --git a/docs/assets/images/button-do-5.png b/docs/assets/images/button-do-5.png new file mode 100644 index 00000000..26425bee Binary files /dev/null and b/docs/assets/images/button-do-5.png differ diff --git a/docs/assets/images/button-dont-1.png b/docs/assets/images/button-dont-1.png new file mode 100644 index 00000000..97a3feee Binary files /dev/null and b/docs/assets/images/button-dont-1.png differ diff --git a/docs/assets/images/button-dont-2.png b/docs/assets/images/button-dont-2.png new file mode 100644 index 00000000..3af3d228 Binary files /dev/null and b/docs/assets/images/button-dont-2.png differ diff --git a/docs/assets/images/button-dont-3.png b/docs/assets/images/button-dont-3.png new file mode 100644 index 00000000..55771f7f Binary files /dev/null and b/docs/assets/images/button-dont-3.png differ diff --git a/docs/assets/images/button-dont-4.png b/docs/assets/images/button-dont-4.png new file mode 100644 index 00000000..a9bf53bf Binary files /dev/null and b/docs/assets/images/button-dont-4.png differ diff --git a/docs/assets/images/button-dont-5.png b/docs/assets/images/button-dont-5.png new file mode 100644 index 00000000..7ab8dbcf Binary files /dev/null and b/docs/assets/images/button-dont-5.png differ diff --git a/docs/assets/images/button-hero.png b/docs/assets/images/button-hero.png new file mode 100644 index 00000000..d8a790b5 Binary files /dev/null and b/docs/assets/images/button-hero.png differ diff --git a/docs/assets/images/button-types-icon.png b/docs/assets/images/button-types-icon.png new file mode 100644 index 00000000..688bb642 Binary files /dev/null and b/docs/assets/images/button-types-icon.png differ diff --git a/docs/assets/images/button-types-primary.png b/docs/assets/images/button-types-primary.png new file mode 100644 index 00000000..61ee7b05 Binary files /dev/null and b/docs/assets/images/button-types-primary.png differ diff --git a/docs/assets/images/button-types-secondary.png b/docs/assets/images/button-types-secondary.png new file mode 100644 index 00000000..ebf90e28 Binary files /dev/null and b/docs/assets/images/button-types-secondary.png differ diff --git a/docs/assets/images/checkbox-do-1.png b/docs/assets/images/checkbox-do-1.png new file mode 100644 index 00000000..5eb5775e Binary files /dev/null and b/docs/assets/images/checkbox-do-1.png differ diff --git a/docs/assets/images/checkbox-do-2.png b/docs/assets/images/checkbox-do-2.png new file mode 100644 index 00000000..c83d2052 Binary files /dev/null and b/docs/assets/images/checkbox-do-2.png differ diff --git a/docs/assets/images/checkbox-do-3.png b/docs/assets/images/checkbox-do-3.png new file mode 100644 index 00000000..ede459a7 Binary files /dev/null and b/docs/assets/images/checkbox-do-3.png differ diff --git a/docs/assets/images/checkbox-do-4.png b/docs/assets/images/checkbox-do-4.png new file mode 100644 index 00000000..394aacb9 Binary files /dev/null and b/docs/assets/images/checkbox-do-4.png differ diff --git a/docs/assets/images/checkbox-dont-1.png b/docs/assets/images/checkbox-dont-1.png new file mode 100644 index 00000000..254e72b5 Binary files /dev/null and b/docs/assets/images/checkbox-dont-1.png differ diff --git a/docs/assets/images/checkbox-dont-2.png b/docs/assets/images/checkbox-dont-2.png new file mode 100644 index 00000000..8e09c827 Binary files /dev/null and b/docs/assets/images/checkbox-dont-2.png differ diff --git a/docs/assets/images/checkbox-dont-3.png b/docs/assets/images/checkbox-dont-3.png new file mode 100644 index 00000000..6e9f9b9a Binary files /dev/null and b/docs/assets/images/checkbox-dont-3.png differ diff --git a/docs/assets/images/checkbox-dont-4.png b/docs/assets/images/checkbox-dont-4.png new file mode 100644 index 00000000..630bbac7 Binary files /dev/null and b/docs/assets/images/checkbox-dont-4.png differ diff --git a/docs/assets/images/checkbox-hero.png b/docs/assets/images/checkbox-hero.png new file mode 100644 index 00000000..c250eb84 Binary files /dev/null and b/docs/assets/images/checkbox-hero.png differ diff --git a/docs/assets/images/data-grid-do-1.png b/docs/assets/images/data-grid-do-1.png new file mode 100644 index 00000000..bb186a71 Binary files /dev/null and b/docs/assets/images/data-grid-do-1.png differ diff --git a/docs/assets/images/data-grid-do-2.png b/docs/assets/images/data-grid-do-2.png new file mode 100644 index 00000000..1b544cc2 Binary files /dev/null and b/docs/assets/images/data-grid-do-2.png differ diff --git a/docs/assets/images/data-grid-dont-1.png b/docs/assets/images/data-grid-dont-1.png new file mode 100644 index 00000000..ddb43e99 Binary files /dev/null and b/docs/assets/images/data-grid-dont-1.png differ diff --git a/docs/assets/images/data-grid-dont-2.png b/docs/assets/images/data-grid-dont-2.png new file mode 100644 index 00000000..12c8ef8d Binary files /dev/null and b/docs/assets/images/data-grid-dont-2.png differ diff --git a/docs/assets/images/data-grid-hero.png b/docs/assets/images/data-grid-hero.png new file mode 100644 index 00000000..f6aeb0f8 Binary files /dev/null and b/docs/assets/images/data-grid-hero.png differ diff --git a/docs/assets/images/divider-do-1.png b/docs/assets/images/divider-do-1.png new file mode 100644 index 00000000..d5ebfabf Binary files /dev/null and b/docs/assets/images/divider-do-1.png differ diff --git a/docs/assets/images/divider-do-2.png b/docs/assets/images/divider-do-2.png new file mode 100644 index 00000000..5cae55a3 Binary files /dev/null and b/docs/assets/images/divider-do-2.png differ diff --git a/docs/assets/images/divider-dont-1.png b/docs/assets/images/divider-dont-1.png new file mode 100644 index 00000000..26e5360b Binary files /dev/null and b/docs/assets/images/divider-dont-1.png differ diff --git a/docs/assets/images/divider-dont-2.png b/docs/assets/images/divider-dont-2.png new file mode 100644 index 00000000..6e30b87d Binary files /dev/null and b/docs/assets/images/divider-dont-2.png differ diff --git a/docs/assets/images/divider-hero.png b/docs/assets/images/divider-hero.png new file mode 100644 index 00000000..f22b9a2a Binary files /dev/null and b/docs/assets/images/divider-hero.png differ diff --git a/docs/assets/images/dropdown-do-1.png b/docs/assets/images/dropdown-do-1.png new file mode 100644 index 00000000..0d516dfb Binary files /dev/null and b/docs/assets/images/dropdown-do-1.png differ diff --git a/docs/assets/images/dropdown-do-2.png b/docs/assets/images/dropdown-do-2.png new file mode 100644 index 00000000..91d2c1f6 Binary files /dev/null and b/docs/assets/images/dropdown-do-2.png differ diff --git a/docs/assets/images/dropdown-do-3.png b/docs/assets/images/dropdown-do-3.png new file mode 100644 index 00000000..908eab81 Binary files /dev/null and b/docs/assets/images/dropdown-do-3.png differ diff --git a/docs/assets/images/dropdown-dont-1.png b/docs/assets/images/dropdown-dont-1.png new file mode 100644 index 00000000..3e9e1cb4 Binary files /dev/null and b/docs/assets/images/dropdown-dont-1.png differ diff --git a/docs/assets/images/dropdown-dont-2.png b/docs/assets/images/dropdown-dont-2.png new file mode 100644 index 00000000..9210473f Binary files /dev/null and b/docs/assets/images/dropdown-dont-2.png differ diff --git a/docs/assets/images/dropdown-dont-3.png b/docs/assets/images/dropdown-dont-3.png new file mode 100644 index 00000000..2f0560db Binary files /dev/null and b/docs/assets/images/dropdown-dont-3.png differ diff --git a/docs/assets/images/dropdown-hero.png b/docs/assets/images/dropdown-hero.png new file mode 100644 index 00000000..54bebc92 Binary files /dev/null and b/docs/assets/images/dropdown-hero.png differ diff --git a/docs/assets/images/img-placeholder.png b/docs/assets/images/img-placeholder.png new file mode 100644 index 00000000..4c4ab1b3 Binary files /dev/null and b/docs/assets/images/img-placeholder.png differ diff --git a/docs/assets/images/link-do-1.png b/docs/assets/images/link-do-1.png new file mode 100644 index 00000000..aec0a1c2 Binary files /dev/null and b/docs/assets/images/link-do-1.png differ diff --git a/docs/assets/images/link-do-2.png b/docs/assets/images/link-do-2.png new file mode 100644 index 00000000..ea008131 Binary files /dev/null and b/docs/assets/images/link-do-2.png differ diff --git a/docs/assets/images/link-dont-1.png b/docs/assets/images/link-dont-1.png new file mode 100644 index 00000000..4d460e49 Binary files /dev/null and b/docs/assets/images/link-dont-1.png differ diff --git a/docs/assets/images/link-dont-2.png b/docs/assets/images/link-dont-2.png new file mode 100644 index 00000000..cceab93d Binary files /dev/null and b/docs/assets/images/link-dont-2.png differ diff --git a/docs/assets/images/link-hero.png b/docs/assets/images/link-hero.png new file mode 100644 index 00000000..18d13fe3 Binary files /dev/null and b/docs/assets/images/link-hero.png differ diff --git a/docs/assets/images/option-hero.png b/docs/assets/images/option-hero.png new file mode 100644 index 00000000..e63a73b8 Binary files /dev/null and b/docs/assets/images/option-hero.png differ diff --git a/docs/assets/images/panels-do-1.png b/docs/assets/images/panels-do-1.png new file mode 100644 index 00000000..c70b159e Binary files /dev/null and b/docs/assets/images/panels-do-1.png differ diff --git a/docs/assets/images/panels-do-2.png b/docs/assets/images/panels-do-2.png new file mode 100644 index 00000000..0497f0f8 Binary files /dev/null and b/docs/assets/images/panels-do-2.png differ diff --git a/docs/assets/images/panels-do-3.png b/docs/assets/images/panels-do-3.png new file mode 100644 index 00000000..f974866e Binary files /dev/null and b/docs/assets/images/panels-do-3.png differ diff --git a/docs/assets/images/panels-dont-1.png b/docs/assets/images/panels-dont-1.png new file mode 100644 index 00000000..4097acea Binary files /dev/null and b/docs/assets/images/panels-dont-1.png differ diff --git a/docs/assets/images/panels-dont-2.png b/docs/assets/images/panels-dont-2.png new file mode 100644 index 00000000..4014eb99 Binary files /dev/null and b/docs/assets/images/panels-dont-2.png differ diff --git a/docs/assets/images/panels-dont-3.png b/docs/assets/images/panels-dont-3.png new file mode 100644 index 00000000..dc0dcced Binary files /dev/null and b/docs/assets/images/panels-dont-3.png differ diff --git a/docs/assets/images/panels-hero.png b/docs/assets/images/panels-hero.png new file mode 100644 index 00000000..52983fd7 Binary files /dev/null and b/docs/assets/images/panels-hero.png differ diff --git a/docs/assets/images/progress-ring-do-1.png b/docs/assets/images/progress-ring-do-1.png new file mode 100644 index 00000000..0257df48 Binary files /dev/null and b/docs/assets/images/progress-ring-do-1.png differ diff --git a/docs/assets/images/progress-ring-do-2.png b/docs/assets/images/progress-ring-do-2.png new file mode 100644 index 00000000..75b502ba Binary files /dev/null and b/docs/assets/images/progress-ring-do-2.png differ diff --git a/docs/assets/images/progress-ring-dont-1.png b/docs/assets/images/progress-ring-dont-1.png new file mode 100644 index 00000000..61bfbaba Binary files /dev/null and b/docs/assets/images/progress-ring-dont-1.png differ diff --git a/docs/assets/images/progress-ring-dont-2.png b/docs/assets/images/progress-ring-dont-2.png new file mode 100644 index 00000000..1de742fa Binary files /dev/null and b/docs/assets/images/progress-ring-dont-2.png differ diff --git a/docs/assets/images/progress-ring-hero.png b/docs/assets/images/progress-ring-hero.png new file mode 100644 index 00000000..2896c15b Binary files /dev/null and b/docs/assets/images/progress-ring-hero.png differ diff --git a/docs/assets/images/radio-do-1.png b/docs/assets/images/radio-do-1.png new file mode 100644 index 00000000..f7e643c8 Binary files /dev/null and b/docs/assets/images/radio-do-1.png differ diff --git a/docs/assets/images/radio-do-2.png b/docs/assets/images/radio-do-2.png new file mode 100644 index 00000000..9469ac3b Binary files /dev/null and b/docs/assets/images/radio-do-2.png differ diff --git a/docs/assets/images/radio-do-3.png b/docs/assets/images/radio-do-3.png new file mode 100644 index 00000000..d22df806 Binary files /dev/null and b/docs/assets/images/radio-do-3.png differ diff --git a/docs/assets/images/radio-dont-1.png b/docs/assets/images/radio-dont-1.png new file mode 100644 index 00000000..4e7bfb9a Binary files /dev/null and b/docs/assets/images/radio-dont-1.png differ diff --git a/docs/assets/images/radio-dont-2.png b/docs/assets/images/radio-dont-2.png new file mode 100644 index 00000000..0ab0868a Binary files /dev/null and b/docs/assets/images/radio-dont-2.png differ diff --git a/docs/assets/images/radio-dont-3.png b/docs/assets/images/radio-dont-3.png new file mode 100644 index 00000000..786e9e74 Binary files /dev/null and b/docs/assets/images/radio-dont-3.png differ diff --git a/docs/assets/images/radio-group-hero.png b/docs/assets/images/radio-group-hero.png new file mode 100644 index 00000000..7c17f530 Binary files /dev/null and b/docs/assets/images/radio-group-hero.png differ diff --git a/docs/assets/images/radio-hero.png b/docs/assets/images/radio-hero.png new file mode 100644 index 00000000..d9846af4 Binary files /dev/null and b/docs/assets/images/radio-hero.png differ diff --git a/docs/assets/images/tag-do-1.png b/docs/assets/images/tag-do-1.png new file mode 100644 index 00000000..84f31d24 Binary files /dev/null and b/docs/assets/images/tag-do-1.png differ diff --git a/docs/assets/images/tag-dont-1.png b/docs/assets/images/tag-dont-1.png new file mode 100644 index 00000000..ecb28fe9 Binary files /dev/null and b/docs/assets/images/tag-dont-1.png differ diff --git a/docs/assets/images/tag-hero.png b/docs/assets/images/tag-hero.png new file mode 100644 index 00000000..5209f8db Binary files /dev/null and b/docs/assets/images/tag-hero.png differ diff --git a/docs/assets/images/text-area-do-1.png b/docs/assets/images/text-area-do-1.png new file mode 100644 index 00000000..65d84901 Binary files /dev/null and b/docs/assets/images/text-area-do-1.png differ diff --git a/docs/assets/images/text-area-do-2.png b/docs/assets/images/text-area-do-2.png new file mode 100644 index 00000000..d7696c21 Binary files /dev/null and b/docs/assets/images/text-area-do-2.png differ diff --git a/docs/assets/images/text-area-do-3.png b/docs/assets/images/text-area-do-3.png new file mode 100644 index 00000000..23fc43ee Binary files /dev/null and b/docs/assets/images/text-area-do-3.png differ diff --git a/docs/assets/images/text-area-dont-1.png b/docs/assets/images/text-area-dont-1.png new file mode 100644 index 00000000..29cedc2c Binary files /dev/null and b/docs/assets/images/text-area-dont-1.png differ diff --git a/docs/assets/images/text-area-dont-2.png b/docs/assets/images/text-area-dont-2.png new file mode 100644 index 00000000..ebaad193 Binary files /dev/null and b/docs/assets/images/text-area-dont-2.png differ diff --git a/docs/assets/images/text-area-dont-3.png b/docs/assets/images/text-area-dont-3.png new file mode 100644 index 00000000..db15a576 Binary files /dev/null and b/docs/assets/images/text-area-dont-3.png differ diff --git a/docs/assets/images/text-area-hero.png b/docs/assets/images/text-area-hero.png new file mode 100644 index 00000000..4ea1b154 Binary files /dev/null and b/docs/assets/images/text-area-hero.png differ diff --git a/docs/assets/images/text-field-do-1.png b/docs/assets/images/text-field-do-1.png new file mode 100644 index 00000000..4b1c7936 Binary files /dev/null and b/docs/assets/images/text-field-do-1.png differ diff --git a/docs/assets/images/text-field-do-2.png b/docs/assets/images/text-field-do-2.png new file mode 100644 index 00000000..37739b13 Binary files /dev/null and b/docs/assets/images/text-field-do-2.png differ diff --git a/docs/assets/images/text-field-do-3.png b/docs/assets/images/text-field-do-3.png new file mode 100644 index 00000000..db593200 Binary files /dev/null and b/docs/assets/images/text-field-do-3.png differ diff --git a/docs/assets/images/text-field-do-4.png b/docs/assets/images/text-field-do-4.png new file mode 100644 index 00000000..0ccdead8 Binary files /dev/null and b/docs/assets/images/text-field-do-4.png differ diff --git a/docs/assets/images/text-field-dont-1.png b/docs/assets/images/text-field-dont-1.png new file mode 100644 index 00000000..75438726 Binary files /dev/null and b/docs/assets/images/text-field-dont-1.png differ diff --git a/docs/assets/images/text-field-dont-2.png b/docs/assets/images/text-field-dont-2.png new file mode 100644 index 00000000..75633cf8 Binary files /dev/null and b/docs/assets/images/text-field-dont-2.png differ diff --git a/docs/assets/images/text-field-dont-3.png b/docs/assets/images/text-field-dont-3.png new file mode 100644 index 00000000..c215ff90 Binary files /dev/null and b/docs/assets/images/text-field-dont-3.png differ diff --git a/docs/assets/images/text-field-dont-4.png b/docs/assets/images/text-field-dont-4.png new file mode 100644 index 00000000..ecf6d160 Binary files /dev/null and b/docs/assets/images/text-field-dont-4.png differ diff --git a/docs/assets/images/text-field-hero.png b/docs/assets/images/text-field-hero.png new file mode 100644 index 00000000..4249f20b Binary files /dev/null and b/docs/assets/images/text-field-hero.png differ diff --git a/docs/assets/toolkit-artwork.png b/docs/assets/images/toolkit-artwork.png similarity index 100% rename from docs/assets/toolkit-artwork.png rename to docs/assets/images/toolkit-artwork.png diff --git a/docs/assets/toolkit-button-click-test.png b/docs/assets/images/toolkit-button-click-test.png similarity index 100% rename from docs/assets/toolkit-button-click-test.png rename to docs/assets/images/toolkit-button-click-test.png diff --git a/docs/assets/toolkit-button-test.gif b/docs/assets/images/toolkit-button-test.gif similarity index 100% rename from docs/assets/toolkit-button-test.gif rename to docs/assets/images/toolkit-button-test.gif diff --git a/docs/assets/toolkit-theme-test.gif b/docs/assets/images/toolkit-theme-test.gif similarity index 100% rename from docs/assets/toolkit-theme-test.gif rename to docs/assets/images/toolkit-theme-test.gif diff --git a/docs/assets/webview-test.gif b/docs/assets/images/webview-test.gif similarity index 100% rename from docs/assets/webview-test.gif rename to docs/assets/images/webview-test.gif diff --git a/src/badge/README.md b/src/badge/README.md index c4e09832..eadd98c7 100644 --- a/src/badge/README.md +++ b/src/badge/README.md @@ -2,17 +2,32 @@ The `vscode-badge` component is used to highlight an item, attract attention, and/or flag status. -## Attributes - -None +![Badge hero](/docs/assets/images/badge-hero.png) ## Usage -A `vscode-badge` can only contain numbers to follow the conventions of the Visual Studio Code design language. +| ❌ Don't | ✅ Do | +| -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | +| ![Badge with text value](/docs/assets/images/badge-dont-1.png) | ![Badge with number value](/docs/assets/images/badge-do-1.png) | +| Don't use a badge to display text content. Use a [vscode-tag](../tag/README.md) component instead. | Use a badge to display numbers. | + +| ❌ Don't | ✅ Do | +| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | +| ![Badge used to display and error](/docs/assets/images/badge-dont-2.png) | ![Badge showing the number of items in a history view](/docs/assets/images/badge-do-2.png) | +| Don't use a badge to indicate an error. | Use badges to indicate the numbered state of an element. | + +| ❌ Don't | ✅ Do | +| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------- | +| ![Multiple badges on one element](/docs/assets/images/badge-dont-2.png) | ![One badge used for each section in a view](/docs/assets/images/badge-do-3.png) | +| Don't use more than one badge on a single element. | Ensure badges are clearly associated with their parent element. | -If a component that labels an item with a string is desired, see the `vscode-tag` component. +## Implementation + +### Attributes + +None -### Basic Usage +### Basic Badge [Interactive Storybook Example](https://microsoft.github.io/vscode-webview-ui-toolkit/?path=/story/library-badge--default) diff --git a/src/button/README.md b/src/button/README.md index faf5d213..9790ccf3 100644 --- a/src/button/README.md +++ b/src/button/README.md @@ -2,7 +2,48 @@ The `vscode-button` is a web component implementation of a [button element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button). The `vscode-button` also supports several visual appearances––primary, secondary, and icon. -## Attributes +![Button hero](/docs/assets/images/button-hero.png) + +## Usage + +### Types + +| Type | Example | Usage | +| --------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | +| Primary | Primary button | Emphasizes the highest priority action in a view. | +| Secondary | Secondary button | Used for additional actions in a view that already features a primary action. | +| Icon | Icon button | A space-efficient style that renders a single icon to represent a specific action. | + +### Best Practices + +| ❌ Don't | ✅ Do | +| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | +| ![Multiple primary buttons](/docs/assets/images/button-dont-1.png) | ![One primary and multiple secondary buttons](/docs/assets/images/button-do-1.png) | +| Don't use multiple primary buttons in close proximity. | Provide a single primary button with one or more secondary actions | + +| ❌ Don't | ✅ Do | +| ----------------------------------------------------------------------- | ------------------------------------------------------------------- | +| ![Buttons with incorrect casing](/docs/assets/images/button-dont-2.png) | ![Buttons with correct casing](/docs/assets/images/button-do-2.png) | +| Don't use fully capitalized or lowercase text. | Use sentence case for all button text. | + +| ❌ Don't | ✅ Do | +| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| ![Button with a vague label](/docs/assets/images/button-dont-3.png) | ![Button with a clear label](/docs/assets/images/button-do-3.png) | +| Don't use vague action text. | Use clear verbs like "Save" or "Cancel" to ensure users feel confident when peforming actions. | + +| ❌ Don't | ✅ Do | +| ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| ![Button used as a link](/docs/assets/images//button-dont-4.png) | ![Button clearly associated with the view above](/docs/assets/images//button-do-4.png) | +| Don't use buttons as navigational elements. Use a [vscode-link](../link/README.md) instead. | Use buttons to perform actions relevant to the current view. | + +| ❌ Don't | ✅ Do | +| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | +| ![Icon button used for primary action](/docs/assets/images//button-dont-5.png) | ![Icon buttons in a group](/docs/assets/images//button-do-5.png) | +| Don't use an icon button for primary actions. | Use icon buttons for supporting actions in space-constrained layouts. Use icons that convey clear outcomes. | + +## Implementation + +### Attributes | Attribute | Type | Description | | ---------------- | ------- | --------------------------------------------------------------------------------------- | @@ -20,9 +61,7 @@ The `vscode-button` is a web component implementation of a [button element](http | `type` | string | See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes). | | `value` | string | See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes). | -## Usage - -### Basic Usage +### Basic Button [Interactive Storybook Example](https://microsoft.github.io/vscode-webview-ui-toolkit/?path=/story/library-button--default) diff --git a/src/checkbox/README.md b/src/checkbox/README.md index 917b3b99..dd4000c3 100644 --- a/src/checkbox/README.md +++ b/src/checkbox/README.md @@ -2,7 +2,33 @@ The `vscode-checkbox` is a web component implementation of a [checkbox element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input/checkbox). -## Attributes +![Checkbox hero](/docs/assets/images/checkbox-hero.png) + +## Usage + +| ❌ Don't | ✅ Do | +| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ![Image placeholder](/docs/assets/images/checkbox-dont-1.png) | ![Image placeholder](/docs/assets/images/checkbox-do-1.png) | +| Avoid grouping unrelated checkboxes together. | Split related checkboxes into groups of with descriptive labels. It's ok to group up to three loosely-unrelated checkboxes into one group if using a label that generally captures their purpose. | + +| ❌ Don't | ✅ Do | +| ------------------------------------------------------------- | ------------------------------------------------------------------------------- | +| ![Image placeholder](/docs/assets/images/checkbox-dont-2.png) | ![Image placeholder](/docs/assets/images/checkbox-do-2.png) | +| Avoid using horizontal checkbox group layouts. | Arrange checkbox groups vertically to make it easy to scan and compare options. | + +| ❌ Don't | ✅ Do | +| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------- | +| ![Image placeholder](/docs/assets/images/checkbox-dont-3.png) | ![Image placeholder](/docs/assets/images/checkbox-do-3.png) | +| Don't use an ambiguous label that makes it difficult to understand what the checkbox does. | Use checkbox labels that imply clearly opposite states. | + +| ❌ Don't | ✅ Do | +| ------------------------------------------------------------- | ----------------------------------------------------------- | +| ![Image placeholder](/docs/assets/images/checkbox-dont-4.png) | ![Image placeholder](/docs/assets/images/checkbox-do-4.png) | +| Don't use long blocks of text. | Use concise language to describe each option. | + +## Implementation + +### Attributes | Attribute | Type | Description | | ----------- | ------- | ---------------------------------------------------------------------------------------- | @@ -13,15 +39,13 @@ The `vscode-checkbox` is a web component implementation of a [checkbox element]( | `required` | boolean | Indicates that the user must check the checkbox before the owning form can be submitted. | | `value` | string | The string to use as the value of the checkbox when submitting the form | -## Properties +### Properties | Attribute | Type | Description | | --------------- | ------- | ------------------------------------------------------------------------- | | `indeterminate` | boolean | Determines if the element should render the indeterminate checkbox state. | -## Usage - -### Basic Usage +### Basic Checkbox [Interactive Storybook Example](https://microsoft.github.io/vscode-webview-ui-toolkit/?path=/story/library-checkbox--default) diff --git a/src/data-grid/README.md b/src/data-grid/README.md index 91a88575..4bf9641a 100644 --- a/src/data-grid/README.md +++ b/src/data-grid/README.md @@ -1,41 +1,57 @@ # Visual Studio Code Data Grid -The `vscode-data-grid` enables developers to display data in a tabular layout. The data grid is created using three components that work together: +The `vscode-data-grid` enables developers to display data in a tabular layout. + +![Data grid hero](/docs/assets/images/data-grid-hero.png) + +The data grid is created using three components that work together: - ``: The top level container element. - ``: Displays a single row of data associated with a single record or a header row. - ``: Displays a single cell of data within a row. -## Data Grid Attributes +## Usage + +| ❌ Don't | ✅ Do | +| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- | +| ![Data grid used as a simple list](/docs/assets/images/data-grid-dont-1.png) | ![Data grid with a large data set](/docs/assets/images/data-grid-do-1.png) | +| Don't use a data grid in place of a basic list. | Use data grids to list complex data with secondary information. | + +| ❌ Don't | ✅ Do | +| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ![Data grid in a VS Code sidebar](/docs/assets/images/data-grid-dont-2.png) | ![Data grid in a VS Code editor panel](/docs/assets/images/data-grid-do-2.png) | +| Avoid data grids in small containers if possible. | Place data grids in a main content area to display as much information as possible in one view. It's ok to use a data grid in a small container if only using 2-3 small columns that don't scroll horizontally. | + +## Implementation + +### Data Grid Attributes | Attribute | Type | Description | | ----------------------- | ------ | -------------------------------------------------------------------------------------- | | `generate-header` | string | The type of header row that should be generated. Options: `default`, `sticky`, `none`. | | `grid-template-columns` | string | A string that gets applied to the `grid-template-columns` attribute of child rows. | -## Data Grid Row Attributes +### Data Grid Row Attributes | Attribute | Type | Description | | ----------------------- | ------ | -------------------------------------------------------------------- | | `grid-template-columns` | string | A CSS Grid string that defines the column widths of a data grid row. | | `row-type` | string | The type of row. Options: `default`, `header`, `sticky-header`. | -## Data Grid Cell Attributes +### Data Grid Cell Attributes | Attribute | Type | Description | | ------------- | ------ | ----------------------------------------------------- | | `cell-type` | string | The type of cell. Options: `default`, `columnheader`. | | `grid-column` | string | The column index of the cell. | -## Usage - ❗️❗️❗️ Important ❗️❗️❗️ An aria-label of "Data Grid" is automatically defined on all data grids so they are technically accessible out of the box. However, a descriptive and meaningful label that fits the use case or context of the data grid should always be defined to replace the default label so those viewing your data grid with a screen reader can better understand the meaning of the data. For example, if you're using a data grid to display real-time earthquake data, adding an aria-label with the value "Real-Time Earthquakes" would be appropriate. -### Basic Usage +### Basic Data Grid The recommended basic usage of the `vscode-data-grid` is to use JavaScript (or TypeScript) to programmatically populate the rows and cells of the grid using the `rowsData` property as shown below. diff --git a/src/divider/README.md b/src/divider/README.md index 2b698add..a0bcb080 100644 --- a/src/divider/README.md +++ b/src/divider/README.md @@ -2,15 +2,27 @@ The `vscode-divider` is a web component implementation of a [horiztonal rule element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/hr). +![Divider hero](/docs/assets/images/divider-hero.png) + +## Usage + +| ❌ Don't | ✅ Do | +| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | +| ![An editor panel divided into pseudo-views](/docs/assets/images/divider-dont-1.png) | ![A form with with multiple sections separated by a divider](/docs/assets/images/divider-do-1.png) | +| Don't use a divider to create pseudo-views within a webview. | Use dividers to create distinct sections of related content in a single view. | + +| ❌ Don't | ✅ Do | +| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | +| ![A form with dividers between each input](/docs/assets/images/divider-dont-2.png) | ![A form with dividers between sections](/docs/assets/images/divider-do-2.png) | +| Don't split up related form elements with a divider. | Use a divider to separate multiple forms on the same page. | + ## Attributes | Attribute | Type | Description | | --------- | ------ | ---------------------------------------------- | | role | string | Indicates the semantic meaning of the divider. | -## Usage - -### Basic Usage +### Basic Divider [Interactive Storybook Example](https://microsoft.github.io/vscode-webview-ui-toolkit/?path=/story/library-divider--default) diff --git a/src/dropdown/README.md b/src/dropdown/README.md index 0c1ddb4b..9445385e 100644 --- a/src/dropdown/README.md +++ b/src/dropdown/README.md @@ -2,7 +2,30 @@ The `vscode-dropdown` is a web component implementation of a [select element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select). -## Attributes +![Dropdown hero](/docs/assets/images/dropdown-hero.png) + +## Usage + +| ❌ Don't | ✅ Do | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| ![Dropdown with two options](/docs/assets/images/dropdown-dont-1.png) | ![Dropdown with many options](/docs/assets/images/dropdown-do-1.png) | +| Don't use a dropdown for selections with with less than three options. Try a [checkbox group](../checkbox/README.md) or [radio group](../radio-group/README.md) instead. | Use dropdowns for selections with many unique options. | + +| ❌ Don't | ✅ Do | +| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | +| ![Dropdown with overflowing options](/docs/assets/images/dropdown-dont-2.png) | ![Dropdown options with short labels](/docs/assets/images/dropdown-do-2.png) | +| Avoid overflowing text in dropdown list options. | Use concise language to describe a selection. | + +| ❌ Don't | ✅ Do | +| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| ![Dropdown without label with no supporting context](/docs/assets/images/dropdown-dont-3.png) | ![Dropdown without label with supporting context](/docs/assets/images/dropdown-do-3.png) | +| Don't use a dropdown without a descriptive label without supporting context. | Use dropdowns without labels sparingly in situations where its purpose can easily be identified or if space is limited. | + +## Implementation + +The `vscode-dropdown` component must be used with the `vscode-option` component. + +### Attributes | Attribute | Type | Description | | ---------- | ------- | -------------------------------------------------------------------------------------------- | @@ -10,11 +33,7 @@ The `vscode-dropdown` is a web component implementation of a [select element](ht | `open` | boolean | If true, toggles the dropdown to the open position. | | `position` | string | Reflects the placement for the listbox when the dropdown is open. Options: `above`, `below`. | -## Usage - -The `vscode-dropdown` component must be used with the `vscode-option` component. - -### Basic Usage +### Basic Dropdown [Interactive Storybook Example](https://microsoft.github.io/vscode-webview-ui-toolkit/?path=/story/library-dropdown--default) diff --git a/src/link/README.md b/src/link/README.md index f9a0049d..3972244d 100644 --- a/src/link/README.md +++ b/src/link/README.md @@ -2,7 +2,23 @@ The `vscode-link` is a web component implementation of an [anchor element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a). -## Attributes +![Link hero](/docs/assets/images/link-hero.png) + +## Usage + +| ❌ Don't | ✅ Do | +| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | +| ![Link used for a refresh action](/docs/assets/images/link-dont-1.png) | ![Link used to navigate](/docs/assets/images/link-do-1.png) | +| Don't use a link for actions or commands. Try a [button](../button/README.md) instead. | Use a link to navigate to another location in a project or on the web. | + +| ❌ Don't | ✅ Do | +| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| ![Link with text that fails to convey its purpose](/docs/assets/images/link-dont-2.png) | ![Link with clear language that conveys its purpose](/docs/assets/images/link-do-2.png) | +| Avoid vague link text. | Use descriptive language that provides context to what is being linked. Use inline links with text that provides additional information. | + +## Implementation + +### Attributes | Attribute | Type | Description | | ---------------- | ------- | ---------------------------------------------------------------------------------- | @@ -15,9 +31,7 @@ The `vscode-link` is a web component implementation of an [anchor element](https | `target` | string | See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attributes). | | `type` | string | See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attributes). | -## Usage - -### Basic Usage (With Href Attribute) +### Basic Link (With Href Attribute) [Interactive Storybook Example](https://microsoft.github.io/vscode-webview-ui-toolkit/?path=/story/library-link--default) diff --git a/src/option/README.md b/src/option/README.md index 2e7f189a..cf7c7a60 100644 --- a/src/option/README.md +++ b/src/option/README.md @@ -2,9 +2,15 @@ The `vscode-option` is a web component implementation of an [option](https://w3c.github.io/aria/#option). -The `vscode-option` component will only provide internals related to form association when used within a form-associated component. See the `vscode-dropdown` component for more details. +![Option hero](/docs/assets/images/option-hero.png) -## Attributes +## Usage + +The `vscode-option` component will only provide internals related to form association when used within a form-associated component. See the [vscode-dropdown](../dropdown/README.md) component for more details. + +## Implementation + +### Attributes | Attribute | Type | Description | | ---------- | ------- | ------------------------------------------------------------------- | @@ -12,9 +18,7 @@ The `vscode-option` component will only provide internals related to form associ | `selected` | boolean | The selected attribute value. This sets the initial selected value. | | `value` | string | The initial value of the option. | -## Usage - -### Basic Usage +### Basic Option [Interactive Storybook Example](https://microsoft.github.io/vscode-webview-ui-toolkit/?path=/story/library-option--default) diff --git a/src/panels/README.md b/src/panels/README.md index 4a572233..dc4bb0ea 100644 --- a/src/panels/README.md +++ b/src/panels/README.md @@ -1,27 +1,48 @@ # Visual Studio Code Panels -The `vscode-panels` component is a web component implementation of a [tab](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/Tab_Role). The component is created using three components that work together to interchangably display different content: +The `vscode-panels` component is a web component implementation of a [tab](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/Tab_Role). + +![Panel hero](/docs/assets/images/panels-hero.png) + +The component is created using three components that work together to interchangably display different content: - ``: The top level container element. - ``: Renders the panel tab that will be associated with a panel view. - ``: The container element that will hold content associated with a given tab. -## Panels Attributes +## Usage + +| ❌ Don't | ✅ Do | +| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| ![Tab panel with too many tabs](/docs/assets/images/panels-dont-1.png) | ![Tab panel with several clearly labeled tabs](/docs/assets/images/panels-do-1.png) | +| Don't use more than six panel tabs to organize your extensions views to reduce load on users. | Structure content into as few tabs as possible. | + +| ❌ Don't | ✅ Do | +| ---------------------------------------------------------------------------- | --------------------------------------------------------------- | +| ![Tab panel with random tab ordering](/docs/assets/images/panels-dont-2.png) | ![Image placeholder](/docs/assets/images/panels-do-2.png) | +| Don't use a random tab order. | Tabs with related content should be grouped next to each other. | + +| ❌ Don't | ✅ Do | +| -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ![Tab featuring a very long label with multiple categories](/docs/assets/images/panels-dont-3.png) | ![Image placeholder](/docs/assets/images/panels-do-3.png) | +| Don't use too many words in a tab label or group too many sections in a single tab. | Use concise titles to ensure users know what to expect in each tab. Consider splitting content into multiple tabs if one panel contains many distinct categories of content. | + +## Implementation + +### Panels Attributes | Attribute | Type | Description | | ---------- | ------ | ------------------------------- | | `activeid` | string | The id of the active panel tab. | -## Panel Tab Attributes +### Panel Tab Attributes None -## Panel View Attributes +### Panel View Attributes None -## Usage - **❗️❗️❗️ Important ❗️❗️❗️** An aria-label of "Panels" is automatically defined on all panels components so they are technically accessible out of the box. However, a descriptive and meaningful label that fits the use case or context of the panels component should always be defined to replace the default label so those viewing your panels component with a screen reader can better understand the meaning of what's being displayed. @@ -105,7 +126,7 @@ To apply styling to multiple `` components (but not all): _Finally, an important detail to be aware of is that `
` tags are [known to not to play well with flexboxes](https://stackoverflow.com/questions/45087054/br-is-not-friendly-with-the-flexbox). So if you absolutely need that tag you should likely opt out of the default flexbox behavior._ -### Basic Usage +### Basic Panel Note: Adding a unique ID to each `` and `` component is a convention that helps with easily styling and identifying each tab and view component, but it is not explicitly required unless the `activeid` attribute is being used as demonstrated in the next section. diff --git a/src/progress-ring/README.md b/src/progress-ring/README.md index 16104b46..0d624f07 100644 --- a/src/progress-ring/README.md +++ b/src/progress-ring/README.md @@ -2,13 +2,27 @@ The `vscode-progress-ring` component is used to indicate an indeterminate loading state. -## Attributes - -None +![Progress ring hero](/docs/assets/images/progress-ring-hero.png) ## Usage -### Basic Usage +| ❌ Don't | ✅ Do | +| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | +| ![Progress ring showing indicating a user progress's in a workflow ](/docs/assets/images/progress-ring-dont-1.png) | ![Image placeholder](/docs/assets/images/progress-ring-do-1.png) | +| Don't use a Progress Ring to indicate user progress on a multi-step task. | Indicate indeterminate progress while the extension waits for something to load or to finish executing. | + +| ❌ Don't | ✅ Do | +| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| ![Two progress rings in close proximity](/docs/assets/images/progress-ring-dont-2.png) | ![Two progress rings in distinct sections](/docs/assets/images/progress-ring-do-2.png) | +| Don't use multiple Progress Rings in close proximity. | Use a single Progress Ring in a view. If multiple must be used, ensure they are in clearly defined sections of the extension. | + +## Implementation + +### Attributes + +None + +### Basic Progress Ring The progress ring displays a looping animation to indicate an indeterminate state where the wait time is unspecified. diff --git a/src/radio-group/README.md b/src/radio-group/README.md index dd624080..dd0c2aa8 100644 --- a/src/radio-group/README.md +++ b/src/radio-group/README.md @@ -1,6 +1,29 @@ # Visual Studio Code Radio Group -The `vscode-radio-group` is a web component implementation of a [radio group](https://w3c.github.io/aria-practices/#radiobutton). While any DOM content is permissible as a child of the `vscode-radio-group`, only `vscode-radio` content and slotted content with a role of `radio` will receive keyboard support. +The `vscode-radio-group` is a web component implementation of a [radio group](https://w3c.github.io/aria-practices/#radiobutton). + +![Radio group hero](/docs/assets/images/radio-group-hero.png) + +## Usage + +| ❌ Don't | ✅ Do | +| ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | +| ![Radio buttons that indicate multiple options can be selected](/docs/assets/images/radio-dont-1.png) | ![Radio buttons with one clear possible selection](/docs/assets/images/radio-do-1.png) | +| Don't use radio buttons when more than one selection is possible. Try using [checkboxes](../checkbox/README.md) instead. | Use radio groups for options that feature a single selection at a time. | + +| ❌ Don't | ✅ Do | +| ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | +| ![Radio buttons arranged in a horizontal orientation](/docs/assets/images/radio-dont-2.png) | ![Radio buttons arranged in a vertical orientation](/docs/assets/images/radio-do-2.png) | +| Avoid using horizontal radio group layouts. | Arrange radio groups vertically to make it easy to scan and compare options. | + +| ❌ Don't | ✅ Do | +| --------------------------------------------------------------------------- | ------------------------------------------------------------------------ | +| ![Radio options with multi-line text](/docs/assets/images/radio-dont-3.png) | ![Radio buttons with concise labels](/docs/assets/images/radio-do-3.png) | +| Don't use long blocks of text. | Use concise language to describe each option. | + +## Implementation + +While any DOM content is permissible as a child of the `vscode-radio-group`, only `vscode-radio` content and slotted content with a role of `radio` will receive keyboard support. ## Attributes @@ -11,9 +34,7 @@ The `vscode-radio-group` is a web component implementation of a [radio group](ht | `orientation` | string | The orientation of the group. Options: `horiztonal`, `vertical`. | | `readonly` | boolean | When true, the child radios will be immutable by user interaction. | -## Usage - -### Basic Usage +### Basic Radio Group [Interactive Storybook Example](https://microsoft.github.io/vscode-webview-ui-toolkit/?path=/story/library-radio-group--default) diff --git a/src/radio/README.md b/src/radio/README.md index 95cc0b91..fdf7dd55 100644 --- a/src/radio/README.md +++ b/src/radio/README.md @@ -2,6 +2,12 @@ The `vscode-radio` is a web component implementation of a [radio element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/radio). +![Radio hero](/docs/assets/images/radio-hero.png) + +## Usage + +For guidelines on usage in an extension, see the [vscode-radio-group](../radio-group/README.md) component. + ## Attributes | Attribute | Type | Description | @@ -11,9 +17,9 @@ The `vscode-radio` is a web component implementation of a [radio element](https: | `readonly` | boolean | Indicates whether the radio is checked or not. | | `value` | string | The string to use as the value of the radio. | -## Usage +## Implementation -### Basic Usage +### Basic Radio [Interactive Storybook Example](https://microsoft.github.io/vscode-webview-ui-toolkit/?path=/story/library-radio--default) diff --git a/src/tag/README.md b/src/tag/README.md index 51ba2e24..b3b57de9 100644 --- a/src/tag/README.md +++ b/src/tag/README.md @@ -2,17 +2,22 @@ The `vscode-tag` component is used to label an item, attract attention, and/or flag status. -## Attributes - -None +![Tag hero](/docs/assets/images/tag-hero.png) ## Usage -A `vscode-tag` should only contain text and will be automatically be converted uppercase to follow the conventions of the Visual Studio Code design language. +| ❌ Don't | ✅ Do | +| --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | +| ![A tag incorrectly displaying numbers](/docs/assets/images/tag-dont-1.png) | ![A tag using a text label](/docs/assets/images/tag-do-1.png) | +| Don't use tags to display numbers. If a component that highlights an item with a number is desired, see the [vscode-badge](../badge/README.md) component. | Use tags as text labels to indicate purpose or status for content. | + +## Implementation -If a component that highlights an item with a number is desired, see the `vscode-badge` component. +### Attributes + +None -### Basic Usage +### Basic Tag [Interactive Storybook Example](https://microsoft.github.io/vscode-webview-ui-toolkit/?path=/story/library-tag--default) diff --git a/src/text-area/README.md b/src/text-area/README.md index 5a25951b..5dab42e9 100644 --- a/src/text-area/README.md +++ b/src/text-area/README.md @@ -2,7 +2,30 @@ The `vscode-text-area` is a web component implementation of a [text area element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea). -## Attributes +![Text area hero](/docs/assets/images/text-area-hero.png) + +## Usage + +Read the [text-field](../text-field/README.md) usage guidelines for general guidance when using text inputs. + +| ❌ Don't | ✅ Do | +| ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | +| ![Text area with one line of text](/docs/assets/images/text-area-dont-1.png) | ![Text area with multiple lines of text](/docs/assets/images/text-area-do-2.png) | +| Don't use a text area for inputs requiring only a single line of text. Use a [text-field](../text-field/README.md) component instead. | Use text areas for longer text blocks that span multiple lines. | + +| ❌ Don't | ✅ Do | +| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| ![Text area being resized until content flows out of view](/docs/assets/images/text-area-dont-2.png) | ![Text area being resized causing layout reflow](/docs/assets/images/text-area-do-2.png) | +| Don't let a resizable text area break an extension's layout when resized. | Ensure your layout reflows appropriately when a text area is resized vertically, horizontally, or both. | + +| ❌ Don't | ✅ Do | +| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| ![Text area without label](/docs/assets/images/text-area-dont-3.png) | ![Text area without label with supporting context](/docs/assets/images/text-area-do-3.png) | +| Don't use a text area without a label without any supporting context. | Sparingly use text areas without labels in contexts where their purpose can be easily indentified. | + +## Implementation + +### Attributes | Attribute | Type | Description | | ------------- | ------- | ------------------------------------------------------------------------------------------ | @@ -18,9 +41,7 @@ The `vscode-text-area` is a web component implementation of a [text area element | `rows` | number | Sizes the component vertically by a number of character rows. | | `value` | string | The value (i.e. content) of the text area. | -## Usage - -### Basic Usage +### Basic Text Area [Interactive Storybook Example](https://microsoft.github.io/vscode-webview-ui-toolkit/?path=/story/library-text-area--default) diff --git a/src/text-field/README.md b/src/text-field/README.md index 1b65df2b..9f016ff2 100644 --- a/src/text-field/README.md +++ b/src/text-field/README.md @@ -2,7 +2,33 @@ The `vscode-text-field` is a web component implementation of a [text field element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input/text). -## Attributes +![Text field hero](/docs/assets/images/text-field-hero.png) + +## Usage + +| ❌ Don't | ✅ Do | +| ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | +| ![Text field with overflowing text](/docs/assets/images/text-field-dont-1.png) | ![Text field with a short value](/docs/assets/images/text-field-do-1.png) | +| Don't use a text field for inputs that are greater than a single line of text. Use a [text-area](../text-area/README.md) component instead. | Use text fields for short input values. | + +| ❌ Don't | ✅ Do | +| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | +| ![Text field without a formal label](/docs/assets/images/text-field-dont-2.png) | ![Text label with a descriptive label](/docs/assets/images/text-field-do-2.png) | +| Don't use a placeholder value instead of a label unless absolutely necessary. | Use descriptive labels to help users understand the text fields purpose. | + +| ❌ Don't | ✅ Do | +| ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | +| ![Text field with important information as a placeholder value](/docs/assets/images/text-field-dont-3.png) | ![Text field with helper text below](/docs/assets/images/text-field-do-3.png) | +| Don't include critical information in a placeholder value. | Use helper text if necessary to provide more information about the purpose of the text field. | + +| ❌ Don't | ✅ Do | +| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | +| ![Text field with an icon providing little value](/docs/assets/images/text-field-dont-4.png) | ![Text field with a search icon](/docs/assets/images/text-field-do-4.png) | +| Don't use decorative icons in a text field. | Use icons to help users quickly identify the purpose of a text field—especially if no label is used. | + +## Implementation + +### Attributes | Attribute | Type | Description | | ------------- | ------- | ------------------------------------------------------------------------------------------ | @@ -16,9 +42,7 @@ The `vscode-text-field` is a web component implementation of a [text field eleme | `type` | string | Sets the text field type. | | `value` | string | The value (i.e. content) of the text field. | -## Usage - -### Basic Usage +### Basic Text Field [Interactive Storybook Example](https://microsoft.github.io/vscode-webview-ui-toolkit/?path=/story/library-text-field--default)