Merge branch 'next' into autoload

The reason for the problems is that the error event does
not escape from the shadow dom.
Thus it cannot be awaited for in the test

Co-authored-by: Dominikus Hellgartner <dominikus.hellgartner@gmail.com>

.editorconfig

@@ -1,4 +1,4 @@
-# http://editorconfig.org
+# https://editorconfig.org
 
 root = true
 

.eslintignore

@@ -0,0 +1,10 @@
+.cache
+docs/dist
+docs/search.json
+docs/**/*.min.js
+dist
+examples
+node_modules
+src/react
+scripts
+

.eslintrc.cjs

@@ -0,0 +1,193 @@
+/* eslint-env node */
+
+module.exports = {
+  plugins: [
+    '@typescript-eslint',
+    'wc',
+    'lit',
+    'lit-a11y',
+    'chai-expect',
+    'chai-friendly',
+    'import',
+    'sort-imports-es6-autofix'
+  ],
+  extends: [
+    'eslint:recommended',
+    'plugin:wc/recommended',
+    'plugin:wc/best-practice',
+    'plugin:lit/recommended',
+    'plugin:lit-a11y/recommended'
+  ],
+  env: {
+    es2021: true,
+    browser: true
+  },
+  parserOptions: {
+    sourceType: 'module'
+  },
+  overrides: [
+    {
+      extends: [
+        'plugin:@typescript-eslint/eslint-recommended',
+        'plugin:@typescript-eslint/recommended',
+        'plugin:@typescript-eslint/recommended-requiring-type-checking'
+      ],
+      parser: '@typescript-eslint/parser',
+      parserOptions: {
+        sourceType: 'module',
+        project: './tsconfig.json',
+        tsconfigRootDir: __dirname
+      },
+      files: ['*.ts'],
+      rules: {
+        'default-param-last': 'off',
+        '@typescript-eslint/default-param-last': 'error',
+        'no-empty-function': 'off',
+        '@typescript-eslint/no-empty-function': 'warn',
+        'no-implied-eval': 'off',
+        '@typescript-eslint/no-implied-eval': 'error',
+        'no-invalid-this': 'off',
+        '@typescript-eslint/no-invalid-this': 'error',
+        'no-shadow': 'off',
+        '@typescript-eslint/no-shadow': 'error',
+        'no-throw-literal': 'off',
+        '@typescript-eslint/no-throw-literal': 'error',
+        'no-unused-expressions': 'off',
+        '@typescript-eslint/prefer-regexp-exec': 'off',
+        '@typescript-eslint/no-unused-expressions': 'error',
+        '@typescript-eslint/unbound-method': 'off',
+        '@typescript-eslint/no-non-null-assertion': 'off',
+        '@typescript-eslint/no-floating-promises': 'off',
+        '@typescript-eslint/no-misused-promises': [
+          'error',
+          {
+            checksVoidReturn: false
+          }
+        ],
+        '@typescript-eslint/consistent-type-assertions': [
+          'warn',
+          {
+            assertionStyle: 'as',
+            objectLiteralTypeAssertions: 'never'
+          }
+        ],
+        '@typescript-eslint/consistent-type-imports': 'warn',
+        '@typescript-eslint/no-base-to-string': 'error',
+        '@typescript-eslint/no-confusing-non-null-assertion': 'error',
+        '@typescript-eslint/no-invalid-void-type': 'error',
+        '@typescript-eslint/no-require-imports': 'error',
+        '@typescript-eslint/no-unnecessary-boolean-literal-compare': 'warn',
+        '@typescript-eslint/no-unnecessary-condition': 'off',
+        '@typescript-eslint/no-unnecessary-qualifier': 'warn',
+        '@typescript-eslint/non-nullable-type-assertion-style': 'warn',
+        '@typescript-eslint/prefer-for-of': 'warn',
+        '@typescript-eslint/prefer-optional-chain': 'warn',
+        '@typescript-eslint/prefer-ts-expect-error': 'warn',
+        '@typescript-eslint/prefer-return-this-type': 'error',
+        '@typescript-eslint/prefer-string-starts-ends-with': 'warn',
+        '@typescript-eslint/require-array-sort-compare': 'error',
+        '@typescript-eslint/unified-signatures': 'warn',
+        '@typescript-eslint/array-type': 'warn',
+        '@typescript-eslint/consistent-type-definitions': ['warn', 'interface'],
+        '@typescript-eslint/member-delimiter-style': 'warn',
+        '@typescript-eslint/method-signature-style': 'warn',
+        '@typescript-eslint/no-extraneous-class': 'error',
+        '@typescript-eslint/no-parameter-properties': 'error',
+        '@typescript-eslint/strict-boolean-expressions': 'off'
+      }
+    },
+    {
+      extends: ['plugin:chai-expect/recommended', 'plugin:chai-friendly/recommended'],
+      files: ['*.test.ts'],
+      rules: {
+        '@typescript-eslint/no-unsafe-call': 'off',
+        '@typescript-eslint/no-unused-expressions': 'off'
+      }
+    }
+  ],
+  rules: {
+    'no-template-curly-in-string': 'error',
+    'array-callback-return': 'error',
+    'comma-dangle': 'off',
+    'consistent-return': 'error',
+    curly: 'off',
+    'default-param-last': 'error',
+    eqeqeq: 'error',
+    'lit-a11y/click-events-have-key-events': 'off',
+    'no-constructor-return': 'error',
+    'no-empty-function': 'warn',
+    'no-eval': 'error',
+    'no-extend-native': 'error',
+    'no-extra-bind': 'error',
+    'no-floating-decimal': 'error',
+    'no-implicit-coercion': 'off',
+    'no-implicit-globals': 'error',
+    'no-implied-eval': 'error',
+    'no-invalid-this': 'error',
+    'no-labels': 'error',
+    'no-lone-blocks': 'error',
+    'no-new': 'error',
+    'no-new-func': 'error',
+    'no-new-wrappers': 'error',
+    'no-octal-escape': 'error',
+    'no-proto': 'error',
+    'no-return-assign': 'warn',
+    'no-script-url': 'error',
+    'no-self-compare': 'warn',
+    'no-sequences': 'warn',
+    'no-throw-literal': 'error',
+    'no-unmodified-loop-condition': 'error',
+    'no-unused-expressions': 'warn',
+    'no-useless-call': 'error',
+    'no-useless-concat': 'error',
+    'no-useless-return': 'warn',
+    'prefer-promise-reject-errors': 'error',
+    radix: 'off',
+    'require-await': 'error',
+    'wrap-iife': ['warn', 'inside'],
+    'no-shadow': 'error',
+    'no-array-constructor': 'error',
+    'no-bitwise': 'error',
+    'no-multi-assign': 'warn',
+    'no-new-object': 'error',
+    'no-useless-computed-key': 'warn',
+    'no-useless-rename': 'warn',
+    'no-var': 'error',
+    'prefer-const': 'warn',
+    'prefer-numeric-literals': 'warn',
+    'prefer-object-spread': 'warn',
+    'prefer-rest-params': 'warn',
+    'prefer-spread': 'warn',
+    'prefer-template': 'off',
+    'no-else-return': 'off',
+    'func-names': ['warn', 'never'],
+    'one-var': ['warn', 'never'],
+    'operator-assignment': 'warn',
+    'prefer-arrow-callback': 'warn',
+    'no-restricted-imports': [
+      'warn',
+      {
+        paths: [
+          {
+            name: '.',
+            message: 'Usage of local index imports is not allowed.'
+          },
+          {
+            name: './index',
+            message: 'Import from the source file instead.'
+          }
+        ]
+      }
+    ],
+    'import/no-duplicates': 'warn',
+    'sort-imports-es6-autofix/sort-imports-es6': [
+      2,
+      {
+        ignoreCase: true,
+        ignoreMemberSort: false,
+        memberSyntaxSortOrder: ['none', 'all', 'multiple', 'single']
+      }
+    ],
+    'wc/guard-super-call': 'off'
+  }
+};

.github/ISSUE_TEMPLATE/bug_report.md

@@ -29,8 +29,8 @@ If applicable, add screenshots to help explain the bug.
 
 ### Browser / OS
  - OS: [e.g. Mac, Windows]
- - Browser [e.g. Chrome, Firefox, Safari]
- - Browser version [e.g. 22]
+ - Browser: [e.g. Chrome, Firefox, Safari]
+ - Browser version: [e.g. 22]
 
 ### Additional information
 Provide any additional information about the bug here.

.github/SECURITY.md

@@ -4,4 +4,4 @@ We take security issues in Shoelace very seriously and appreciate your efforts t
 
 To report a security issue, email [cory@abeautifulsite.net](mailto:cory@abeautifulsite.net) and include "SHOELACE SECURITY" in the subject line.
 
-Well respond as soon as possible and keep you updated throughout the process.
+We'll respond as soon as possible and keep you updated throughout the process.

.github/workflows/node.js.yml

@@ -5,28 +5,26 @@ name: Node.js CI
 
 on:
   push:
-    branches: [ next ]
+    branches: [next]
   pull_request:
-    branches: [ next ]
+    branches: [next]
 
 jobs:
   build:
-
     runs-on: ubuntu-latest
 
     strategy:
       matrix:
-        node-version: [14.x, 16.x]
+        node-version: [18.x]
         # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
 
     steps:
-    - uses: actions/checkout@v2
-    - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v2
-      with:
-        node-version: ${{ matrix.node-version }}
-        cache: 'npm'
-    - run: npx playwright install-deps
-    - run: npm ci
-    - run: npm run build --if-present
-    - run: npm test
+      - uses: actions/checkout@v3
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+      - run: npx playwright install-deps
+      - run: npm ci
+      - run: npm run verify

.gitignore

@@ -3,6 +3,5 @@
 docs/dist
 docs/search.json
 dist
-examples
 node_modules
 src/react

.gitpod.yml

@@ -0,0 +1,28 @@
+tasks:
+  - init: npm install && npm run build
+    command: npm run start
+
+ports:
+  - port: 3001
+    onOpen: ignore
+  - port: 4000-4999
+    onOpen: open-preview
+
+github:
+  prebuilds:
+    # enable for the master/default branch (defaults to true)
+    master: true
+    # enable for all branches in this repo (defaults to false)
+    branches: true
+    # enable for pull requests coming from this repo (defaults to true)
+    pullRequests: true
+    # enable for pull requests coming from forks (defaults to false)
+    pullRequestsFromForks: true
+    # add a check to pull requests (defaults to true)
+    addCheck: true
+    # add a "Review in Gitpod" button as a comment to pull requests (defaults to false)
+    addComment: false
+    # add a "Review in Gitpod" button to the pull request's description (defaults to false)
+    addBadge: true
+    # add a label once the prebuild is ready to pull requests (defaults to false)
+    addLabel: true

.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+npx --no-install lint-staged

.prettierignore

@@ -1,10 +1,11 @@
 *.hbs
-*.md
 .cache
 .github
+cspell.json
 dist
-docs/*.md
+docs/search.json
 src/components/icon/icons
+src/react/index.ts
 node_modules
 package-lock.json
 tsconfig.json

.vscode/extensions.json

@@ -1,8 +1,9 @@
 {
   "recommendations": [
-    "ms-vscode.vscode-typescript-tslint-plugin",
+    "dbaeumer.vscode-eslint",
     "esbenp.prettier-vscode",
     "bierner.lit-html",
-    "bashmish.es6-string-css"
+    "bashmish.es6-string-css",
+    "streetsidesoftware.code-spell-checker"
   ]
 }

.vscode/settings.json

@@ -1,4 +1,7 @@
 {
   "editor.formatOnSave": true,
-  "editor.defaultFormatter": "esbenp.prettier-vscode"
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": true
+  }
 }

README.md

@@ -23,7 +23,7 @@ Twitter: [@shoelace_style](https://twitter.com/shoelace_style)
 
 ## Shoemakers 🥾
 
-Shoemakers, or "Shoelace developers," can use this documentation to learn how to build Shoelace from source. You will need Node >= 14 to build and run the project locally. It is preferred, but not required, to use npm 7.
+Shoemakers, or "Shoelace developers," can use this documentation to learn how to build Shoelace from source. You will need Node >= 14.17 to build and run the project locally.
 
 **You don't need to do any of this to use Shoelace!** This page is for people who want to contribute to the project, tinker with the source, or create a custom build of Shoelace.
 

cspell.json

@@ -0,0 +1,167 @@
+{
+  "version": "0.2",
+  "words": [
+    "activedescendant",
+    "allowfullscreen",
+    "animationend",
+    "Animista",
+    "apos",
+    "atrule",
+    "autocorrect",
+    "autofix",
+    "autoload",
+    "autoloader",
+    "autoloading",
+    "autoplay",
+    "bezier",
+    "boxicons",
+    "callout",
+    "callouts",
+    "chatbubble",
+    "checkmark",
+    "claviska",
+    "Clippy",
+    "codebases",
+    "codepen",
+    "colocated",
+    "colour",
+    "combobox",
+    "Composability",
+    "Consolas",
+    "contenteditable",
+    "copydir",
+    "Cotte",
+    "coverpage",
+    "crossorigin",
+    "crutchcorn",
+    "csspart",
+    "cssproperty",
+    "datetime",
+    "describedby",
+    "Docsify",
+    "dropdowns",
+    "easings",
+    "enterkeyhint",
+    "eqeqeq",
+    "erroneou",
+    "errormessage",
+    "esbuild",
+    "exportparts",
+    "fieldsets",
+    "formaction",
+    "formdata",
+    "formenctype",
+    "formmethod",
+    "formnovalidate",
+    "formtarget",
+    "FOUC",
+    "FOUCE",
+    "fullscreen",
+    "gestern",
+    "giga",
+    "globby",
+    "Grayscale",
+    "haspopup",
+    "heroicons",
+    "hexa",
+    "Iconoir",
+    "Iframes",
+    "iife",
+    "inputmode",
+    "ionicon",
+    "ionicons",
+    "jsDelivr",
+    "jsfiddle",
+    "jsonata",
+    "keydown",
+    "keyframes",
+    "Kool",
+    "labelledby",
+    "Laravel",
+    "LaViska",
+    "listbox",
+    "listitem",
+    "litelement",
+    "lowercasing",
+    "Lucide",
+    "maxlength",
+    "Menlo",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "middlewares",
+    "minlength",
+    "monospace",
+    "mousedown",
+    "mouseup",
+    "multiselectable",
+    "nextjs",
+    "nocheck",
+    "noopener",
+    "noreferrer",
+    "novalidate",
+    "outdir",
+    "ParamagicDev",
+    "peta",
+    "petabit",
+    "progressbar",
+    "radiogroup",
+    "Railsbyte",
+    "remixicon",
+    "reregister",
+    "resizer",
+    "resizers",
+    "rgba",
+    "roadmap",
+    "Roboto",
+    "roledescription",
+    "Sapan",
+    "saturationl",
+    "Schilp",
+    "scrollbars",
+    "scrollend",
+    "scroller",
+    "Segoe",
+    "semibold",
+    "slotchange",
+    "spacebar",
+    "stylesheet",
+    "Tabbable",
+    "tabindex",
+    "tabler",
+    "tablist",
+    "tabpanel",
+    "templating",
+    "tera",
+    "testid",
+    "textareas",
+    "textfield",
+    "tinycolor",
+    "transitionend",
+    "treeitem",
+    "Triaging",
+    "turbolinks",
+    "typeof",
+    "unbundles",
+    "unbundling",
+    "unicons",
+    "unsupportive",
+    "valpha",
+    "valuenow",
+    "valuetext",
+    "WEBP",
+    "Webpacker",
+    "wordmark"
+  ],
+  "ignorePaths": [
+    "package.json",
+    "package-lock.json",
+    "docs/assets/examples/include.html",
+    ".vscode/**",
+    "src/translations/!(en).ts",
+    "**/*.min.js"
+  ],
+  "ignoreRegExpList": [
+    "(^|[^a-z])sl[a-z]*(^|[^a-z])"
+  ],
+  "useGitignore": true
+}

custom-elements-manifest.config.js

@@ -1,19 +1,38 @@
-import fs from 'fs';
+import { generateCustomData } from 'cem-plugin-vs-code-custom-data-generator';
 import { parse } from 'comment-parser';
-import pascalCase from 'pascal-case';
+import { pascalCase } from 'pascal-case';
+import commandLineArgs from 'command-line-args';
+import fs from 'fs';
 
 const packageData = JSON.parse(fs.readFileSync('./package.json', 'utf8'));
 const { name, description, version, author, homepage, license } = packageData;
-const noDash = string => string.replace(/^\s?-/, '').trim();
+
+const { outdir } = commandLineArgs([
+  { name: 'litelement', type: String },
+  { name: 'analyze', defaultOption: true },
+  { name: 'outdir', type: String }
+]);
+
+function noDash(string) {
+  return string.replace(/^\s?-/, '').trim();
+}
+
+function replace(string, terms) {
+  terms.forEach(({ from, to }) => {
+    string = string?.replace(from, to);
+  });
+
+  return string;
+}
 
 export default {
   globs: ['src/components/**/*.ts'],
-  exclude: ['**/*.test.ts'],
+  exclude: ['**/*.styles.ts', '**/*.test.ts'],
   plugins: [
     // Append package data
     {
       name: 'shoelace-package-data',
-      packageLinkPhase({ customElementsManifest, context }) {
+      packageLinkPhase({ customElementsManifest }) {
         customElementsManifest.package = { name, description, version, author, homepage, license };
       }
     },
@@ -21,12 +40,12 @@ export default {
     // Parse custom jsDoc tags
     {
       name: 'shoelace-custom-tags',
-      analyzePhase({ ts, node, moduleDoc, context }) {
+      analyzePhase({ ts, node, moduleDoc }) {
         switch (node.kind) {
-          case ts.SyntaxKind.ClassDeclaration:
+          case ts.SyntaxKind.ClassDeclaration: {
             const className = node.name.getText();
             const classDoc = moduleDoc?.declarations?.find(declaration => declaration.name === className);
-            const customTags = ['animation', 'dependency', 'since', 'status'];
+            const customTags = ['animation', 'dependency', 'documentation', 'since', 'status', 'title'];
             let customComments = '/**';
 
             node.jsDoc?.forEach(jsDoc => {
@@ -39,8 +58,8 @@ export default {
               });
             });
 
-            const parsed = parse(customComments + '\n */');
-            parsed[0].tags?.map(t => {
+            const parsed = parse(`${customComments}\n */`);
+            parsed[0].tags?.forEach(t => {
               switch (t.tag) {
                 // Animations
                 case 'animation':
@@ -62,8 +81,10 @@ export default {
                   break;
 
                 // Value-only metadata tags
+                case 'documentation':
                 case 'since':
                 case 'status':
+                case 'title':
                   classDoc[t.tag] = t.name;
                   break;
 
@@ -80,25 +101,67 @@ export default {
                   });
               }
             });
+          }
         }
       }
     },
-
     {
       name: 'shoelace-react-event-names',
-      analyzePhase({ ts, node, moduleDoc, context }) {
+      analyzePhase({ ts, node, moduleDoc }) {
         switch (node.kind) {
-          case ts.SyntaxKind.ClassDeclaration:
+          case ts.SyntaxKind.ClassDeclaration: {
             const className = node.name.getText();
             const classDoc = moduleDoc?.declarations?.find(declaration => declaration.name === className);
 
             if (classDoc?.events) {
-              classDoc.events.map(event => {
+              classDoc.events.forEach(event => {
                 event.reactName = `on${pascalCase(event.name)}`;
               });
             }
+          }
         }
       }
-    }
+    },
+    {
+      name: 'shoelace-translate-module-paths',
+      packageLinkPhase({ customElementsManifest }) {
+        customElementsManifest?.modules?.forEach(mod => {
+          //
+          // CEM paths look like this:
+          //
+          //  src/components/button/button.ts
+          //
+          // But we want them to look like this:
+          //
+          //  components/button/button.js
+          //
+          const terms = [
+            { from: /^src\//, to: '' }, // Strip the src/ prefix
+            { from: /\.(t|j)sx?$/, to: '.js' } // Convert .ts to .js
+          ];
+
+          mod.path = replace(mod.path, terms);
+
+          for (const ex of mod.exports ?? []) {
+            ex.declaration.module = replace(ex.declaration.module, terms);
+          }
+
+          for (const dec of mod.declarations ?? []) {
+            if (dec.kind === 'class') {
+              for (const member of dec.members ?? []) {
+                if (member.inheritedFrom) {
+                  member.inheritedFrom.module = replace(member.inheritedFrom.module, terms);
+                }
+              }
+            }
+          }
+        });
+      }
+    },
+    // Generate custom VS Code data
+    generateCustomData({
+      outdir,
+      cssFileName: null
+    })
   ]
 };

docs/_sidebar.md

@@ -1,23 +1,28 @@
 - Getting Started
+
   - [Overview](/)
   - [Installation](/getting-started/installation)
   - [Usage](/getting-started/usage)
   - [Themes](/getting-started/themes)
   - [Customizing](/getting-started/customizing)
+  - [Form Controls](/getting-started/form-controls)
   - [Localization](/getting-started/localization)
 
 - Frameworks
+
   - [React](/frameworks/react)
   - [Vue](/frameworks/vue)
   - [Angular](/frameworks/angular)
 
 - Resources
+
   - [Community](/resources/community)
   - [Accessibility](/resources/accessibility)
   - [Contributing](/resources/contributing)
   - [Changelog](/resources/changelog)
 
 - Components
+
   - [Alert](/components/alert)
   - [Avatar](/components/avatar)
   - [Badge](/components/badge)
@@ -26,6 +31,8 @@
   - [Button](/components/button)
   - [Button Group](/components/button-group)
   - [Card](/components/card)
+  - [Carousel](/components/carousel)
+  - [Carousel Item](/components/carousel-item)
   - [Checkbox](/components/checkbox)
   - [Color Picker](/components/color-picker)
   - [Details](/components/details)
@@ -33,7 +40,6 @@
   - [Divider](/components/divider)
   - [Drawer](/components/drawer)
   - [Dropdown](/components/dropdown)
-  - [Form](/components/form)
   - [Icon](/components/icon)
   - [Icon Button](/components/icon-button)
   - [Image Comparer](/components/image-comparer)
@@ -41,10 +47,12 @@
   - [Menu](/components/menu)
   - [Menu Item](/components/menu-item)
   - [Menu Label](/components/menu-label)
+  - [Option](/components/option)
   - [Progress Bar](/components/progress-bar)
   - [Progress Ring](/components/progress-ring)
   - [QR Code](/components/qr-code)
   - [Radio](/components/radio)
+  - [Radio Button](/components/radio-button)
   - [Radio Group](/components/radio-group)
   - [Range](/components/range)
   - [Rating](/components/rating)
@@ -59,9 +67,12 @@
   - [Tag](/components/tag)
   - [Textarea](/components/textarea)
   - [Tooltip](/components/tooltip)
+  - [Tree](/components/tree)
+  - [Tree Item](/components/tree-item)
   <!--plop:component-->
 
 - Utilities
+
   - [Animated Image](/components/animated-image)
   - [Animation](/components/animation)
   - [Format Bytes](/components/format-bytes)
@@ -69,12 +80,13 @@
   - [Format Number](/components/format-number)
   - [Include](/components/include)
   - [Mutation Observer](/components/mutation-observer)
+  - [Popup](/components/popup)
   - [Relative Time](/components/relative-time)
   - [Resize Observer](/components/resize-observer)
-  - [Responsive Media](/components/responsive-media)
   - [Visually Hidden](/components/visually-hidden)
 
 - Design Tokens
+
   - [Typography](/tokens/typography)
   - [Color](/tokens/color)
   - [Spacing](/tokens/spacing)
@@ -82,8 +94,10 @@
   - [Border Radius](/tokens/border-radius)
   - [Transition](/tokens/transition)
   - [Z-index](/tokens/z-index)
+  - [More](/tokens/more)
 
 - Tutorials
+
   - [Integrating with Laravel](/tutorials/integrating-with-laravel)
   - [Integrating with NextJS](/tutorials/integrating-with-nextjs)
-  - [Integrating with Rails](/tutorials/integrating-with-rails)
+  - [Integrating with Rails](/tutorials/integrating-with-rails)

docs/assets/images/open-in-gitpod.svg

@@ -0,0 +1,23 @@
+<svg width="160" height="45" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <g filter="url(#filter0_d)">
+    <rect x="2" y="2" width="156" height="40" rx="16" fill="#F9F9F9"/>
+    <path fill-rule="evenodd" clip-rule="evenodd" d="M30.425 11.174c.604 1.114.233 2.53-.83 3.164l-6.986 4.166a.378.378 0 00-.18.325v6.748c0 .134.069.258.18.325l5.714 3.407c.11.066.244.066.354 0l5.714-3.407a.378.378 0 00.18-.325V21.29l-4.986 2.936c-1.067.628-2.416.231-3.015-.886-.6-1.118-.22-2.532.846-3.16l7.008-4.127c2.048-1.206 4.576.345 4.576 2.806v6.718c0 1.803-.924 3.467-2.42 4.36l-5.713 3.407a4.596 4.596 0 01-4.734 0l-5.714-3.408C18.924 29.044 18 27.38 18 25.576V18.83c0-1.803.924-3.467 2.42-4.36l6.985-4.165c1.063-.634 2.415-.245 3.02.87z" fill="url(#paint0_linear)"/>
+    <path fill="#F9F9F9" d="M47 12.5h95v-1H47z"/>
+    <path d="M52.538 27.752c2.744 0 4.844-1.876 4.844-5.152 0-3.108-2.1-5.152-4.844-5.152s-4.802 2.002-4.802 5.152c0 3.29 2.058 5.152 4.802 5.152zm0-1.554c-1.736 0-2.912-1.316-2.912-3.598 0-2.226 1.162-3.598 2.912-3.598s2.954 1.4 2.954 3.598c0 2.31-1.218 3.598-2.954 3.598zm7.89 4.158V27.22c0-.196-.013-.378-.055-.658.434.7 1.022 1.19 2.17 1.19 1.736 0 3.066-1.414 3.066-3.626 0-2.17-1.19-3.682-2.996-3.682-1.078 0-1.806.476-2.24 1.204.042-.28.056-.462.056-.672v-.308H58.72v9.688h1.708zm1.695-3.948c-1.036 0-1.764-.938-1.764-2.31 0-1.414.742-2.296 1.764-2.296 1.092 0 1.75.952 1.75 2.296 0 1.372-.7 2.31-1.75 2.31zm7.866 1.344c1.848 0 3.052-1.078 3.192-2.478h-1.736c-.112.714-.714 1.134-1.456 1.134-1.036 0-1.722-.826-1.736-1.904h4.97v-.378c0-2.226-1.204-3.682-3.29-3.682-1.988 0-3.43 1.47-3.43 3.626 0 2.366 1.442 3.682 3.486 3.682zm-1.75-4.48c.098-.896.756-1.554 1.68-1.554.924 0 1.526.63 1.554 1.554H68.24zm8.006 4.228v-4.004c0-.952.616-1.694 1.456-1.694.798 0 1.288.63 1.288 1.638v4.06h1.708v-4.312c0-1.68-.896-2.744-2.408-2.744-1.078 0-1.722.518-2.1 1.204.042-.266.056-.476.056-.672v-.308h-1.708V27.5h1.708zm8.911-7.868h1.792V17.84h-1.792v1.792zm.042 1.036V27.5h1.708v-6.832h-1.708zm5.097 6.832v-4.004c0-.952.616-1.694 1.456-1.694.798 0 1.288.63 1.288 1.638v4.06h1.708v-4.312c0-1.68-.896-2.744-2.408-2.744-1.078 0-1.722.518-2.1 1.204.042-.266.056-.476.056-.672v-.308h-1.708V27.5h1.708zm13.238.252c1.526 0 2.52-.658 2.982-1.54-.07.322-.098.644-.098.98v.308h1.68v-5.222h-4.34v1.554h2.66v.07c0 1.4-1.134 2.296-2.59 2.296-1.792 0-3.024-1.372-3.024-3.598s1.26-3.598 3.066-3.598c1.302 0 2.17.756 2.296 1.736h1.89c-.182-1.904-1.764-3.29-4.214-3.29-2.954 0-4.928 2.128-4.928 5.152 0 3.136 1.848 5.152 4.62 5.152zm6.063-8.12h1.792V17.84h-1.792v1.792zm.042 1.036V27.5h1.708v-6.832h-1.708zm6.413 6.958c.434 0 .84-.07 1.008-.126v-1.288c-.168.028-.35.042-.518.042-.728 0-1.008-.42-1.008-1.134v-3.094h1.68v-1.358h-1.68v-2.464h-1.708v2.464h-1.554v1.358h1.554v3.346c0 1.526.77 2.254 2.226 2.254zm3.961 2.73V27.22c0-.196-.014-.378-.056-.658.434.7 1.022 1.19 2.17 1.19 1.736 0 3.066-1.414 3.066-3.626 0-2.17-1.19-3.682-2.996-3.682-1.078 0-1.806.476-2.24 1.204.042-.28.056-.462.056-.672v-.308h-1.708v9.688h1.708zm1.694-3.948c-1.036 0-1.764-.938-1.764-2.31 0-1.414.742-2.296 1.764-2.296 1.092 0 1.75.952 1.75 2.296 0 1.372-.7 2.31-1.75 2.31zm7.88 1.344c2.058 0 3.514-1.372 3.514-3.64 0-2.24-1.456-3.668-3.514-3.668-2.044 0-3.5 1.428-3.5 3.668 0 2.268 1.442 3.64 3.5 3.64zm0-1.344c-1.064 0-1.764-.84-1.764-2.296 0-1.484.728-2.31 1.764-2.31 1.05 0 1.778.826 1.778 2.31 0 1.456-.714 2.296-1.778 2.296zm7.551 1.344c1.26 0 1.876-.686 2.142-1.19-.056.238-.056.42-.056.658v.28h1.708v-9.8h-1.708v3.276c0 .21 0 .42.056.672-.392-.658-1.05-1.204-2.114-1.204-1.596 0-3.15 1.218-3.15 3.668 0 2.408 1.316 3.64 3.122 3.64zm.406-1.344c-1.022 0-1.792-.896-1.792-2.31 0-1.358.77-2.296 1.792-2.296s1.778.896 1.778 2.296c0 1.372-.756 2.31-1.778 2.31z" fill="#12100C"/>
+  </g>
+  <defs>
+    <linearGradient id="paint0_linear" x1="33.806" y1="13.629" x2="22.389" y2="30.86" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#FFB45B"/>
+      <stop offset="1" stop-color="#FF8A00"/>
+    </linearGradient>
+    <filter id="filter0_d" x="0" y=".5" width="160" height="44" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+      <feFlood flood-opacity="0" result="BackgroundImageFix"/>
+      <feColorMatrix in="SourceAlpha" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"/>
+      <feOffset dy=".5"/>
+      <feGaussianBlur stdDeviation="1"/>
+      <feColorMatrix values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.1 0"/>
+      <feBlend in2="BackgroundImageFix" result="effect1_dropShadow"/>
+      <feBlend in="SourceGraphic" in2="effect1_dropShadow" result="shape"/>
+    </filter>
+  </defs>
+</svg>

docs/assets/images/undraw-content-team.svg

@@ -41,7 +41,7 @@
             <ellipse id="Oval" fill="#2F2E41" fill-rule="nonzero" cx="103.34581" cy="426.732" rx="10.90314" ry="4.08868"></ellipse>
             <circle id="Oval" fill="#FFFFFF" fill-rule="nonzero" cx="86.99113" cy="358.86008" r="14.71922"></circle>
             <circle id="Oval" fill="#3F3D56" fill-rule="nonzero" cx="86.99113" cy="358.86008" r="4.90642"></circle>
-            <path d="M44.12401,329.71183 C40.64653,314.13804 51.76268,298.4014 68.95262,294.56302 C86.14256,290.72464 102.89683,300.23813 106.37431,315.81192 C109.85179,331.38571 98.45939,337.12961 81.26945,340.96792 C64.07951,344.80623 47.60154,345.28568 44.12401,329.71183 Z" id="Path" fill="#E6E6E6" fill-rule="nonzero"></path>
+            <path d="M44.12401,329.71183 C40.64653,314.13804 51.76268,298.4014 68.95262,294.56302 C86.14256,290.72464 102.89683,300.23813 106.37431,315.81192 C109.85179,331.38571 98.45939,337.12961 81.26945,340.96792 C64.07951,344.80623 47.60154,345.28568 44.12401,329.71183 Z" id="Path" fill="#12a5e9" fill-rule="nonzero"></path>
             <ellipse id="Oval" fill="#2F2E41" fill-rule="nonzero" transform="translate(110.988725, 213.490755) rotate(-69.082170) translate(-110.988725, -213.490755) " cx="110.988725" cy="213.490755" rx="21.53369" ry="6.76007"></ellipse>
             <circle id="Oval" fill="#2F2E41" fill-rule="nonzero" transform="translate(71.181568, 246.012788) rotate(-80.782520) translate(-71.181568, -246.012788) " cx="71.1815681" cy="246.012788" r="43.06735"></circle>
             <rect id="Rectangle" fill="#2F2E41" fill-rule="nonzero" x="51.55595" y="279.81244" width="13.08374" height="23.44171"></rect>
@@ -67,13 +67,13 @@
             <circle id="Oval" fill="#3F3D56" fill-rule="nonzero" cx="725.31949" cy="403.22896" r="4.90642"></circle>
             <ellipse id="Oval" fill="#2F2E41" fill-rule="nonzero" transform="translate(771.918005, 384.148727) rotate(-53.549900) translate(-771.918005, -384.148727) " cx="771.918005" cy="384.148727" rx="21.53368" ry="6.76007"></ellipse>
             <path d="M705.39698,436.33866 C705.39698,432.86466 714.34198,426.00466 724.26778,426.00466 C734.19358,426.00466 743.50006,435.78516 743.50006,439.25914 C743.50006,442.73312 734.19351,438.58514 724.26778,438.58514 C714.34205,438.58514 705.39698,439.81268 705.39698,436.33866 Z" id="Path" fill="#FFFFFF" fill-rule="nonzero" transform="translate(724.448520, 433.325266) rotate(-180.000000) translate(-724.448520, -433.325266) "></path>
-            <path d="M847.1767,378.54172 L611.43117,345.86064 C607.604361,345.32541 604.932725,341.793834 605.45868,337.96574 L631.96057,146.79396 C632.495641,142.967058 636.027329,140.295337 639.85547,140.82147 L875.60098,173.50256 C879.427885,174.037626 882.099609,177.569318 881.57347,181.39746 L855.0716,372.56924 C854.536375,376.396051 851.004794,379.067687 847.1767,378.54172 L847.1767,378.54172 Z" id="Path" fill="#11a5e9" fill-rule="nonzero"></path>
+            <path d="M847.1767,378.54172 L611.43117,345.86064 C607.604361,345.32541 604.932725,341.793834 605.45868,337.96574 L631.96057,146.79396 C632.495641,142.967058 636.027329,140.295337 639.85547,140.82147 L875.60098,173.50256 C879.427885,174.037626 882.099609,177.569318 881.57347,181.39746 L855.0716,372.56924 C854.536375,376.396051 851.004794,379.067687 847.1767,378.54172 L847.1767,378.54172 Z" id="Path" fill="#9358ff" fill-rule="nonzero"></path>
             <path d="M762.72231,318.87957 L642.36784,302.19498 C642.216871,302.176045 642.067969,302.14324 641.92302,302.09698 L712.51355,211.39072 C713.394132,210.238632 714.82651,209.649483 716.262854,209.8486 C717.699198,210.047717 718.917295,211.004295 719.45127,212.35248 L748.48059,283.8148 L749.87186,287.23459 L762.72231,318.87957 Z" id="Path" fill="#FFFFFF" fill-rule="nonzero"></path>
             <polygon id="Path" fill="#000000" fill-rule="nonzero" opacity="0.2" points="762.722 318.879 721.63 313.183 745.864 286.679 747.609 284.77 748.481 283.815 749.872 287.235"></polygon>
             <path d="M829.73481,328.16942 L725.63807,313.73863 L749.87186,287.23463 L751.61612,285.32515 L783.19533,250.78503 C784.29885,249.735613 785.796059,249.204111 787.314261,249.322828 C788.832463,249.441546 790.228856,250.199316 791.15584,251.40751 C791.271244,251.575507 791.375823,251.750689 791.46894,251.93199 L829.73481,328.16942 Z" id="Path" fill="#FFFFFF" fill-rule="nonzero"></path>
             <circle id="Oval" fill="#FFFFFF" fill-rule="nonzero" cx="764.18602" cy="224.18353" r="18"></circle>
-            <rect id="Rectangle" fill="#3F3D56" fill-rule="nonzero" transform="translate(653.262165, 167.923576) rotate(7.892770) translate(-653.262165, -167.923576) " x="642.262129" y="156.923541" width="22.0000711" height="22.0000711"></rect>
-            <path d="M768.18655,374.08068 C771.66403,358.50689 760.54788,342.77022 743.35794,338.93184 C726.168,335.09346 709.41373,344.60692 705.93625,360.18071 C702.45877,375.7545 713.85117,381.49837 731.04111,385.33671 C748.23105,389.17505 764.70908,389.6545 768.18655,374.08068 Z" id="Path" fill="#F2F2F2" fill-rule="nonzero"></path>
+            <rect id="Rectangle" fill="#FFFFFF" fill-rule="nonzero" transform="translate(653.262165, 167.923576) rotate(7.892770) translate(-653.262165, -167.923576) " x="642.262129" y="156.923541" width="22.0000711" height="22.0000711"></rect>
+            <path d="M768.18655,374.08068 C771.66403,358.50689 760.54788,342.77022 743.35794,338.93184 C726.168,335.09346 709.41373,344.60692 705.93625,360.18071 C702.45877,375.7545 713.85117,381.49837 731.04111,385.33671 C748.23105,389.17505 764.70908,389.6545 768.18655,374.08068 Z" id="Path" fill="#12a5e9" fill-rule="nonzero"></path>
             <ellipse id="Oval" fill="#2F2E41" fill-rule="nonzero" transform="translate(735.010556, 473.249892) rotate(-4.181640) translate(-735.010556, -473.249892) " cx="735.010556" cy="473.249892" rx="10.90314" ry="4.08868"></ellipse>
         </g>
     </g>

docs/assets/plugins/code-block/code-block.css

@@ -132,17 +132,13 @@
   box-shadow: 0 0 0 1px var(--sl-color-primary-400);
   border-right-color: transparent;
   background-color: var(--sl-color-primary-50);
-  color: var(--sl-color-primary-700);
+  color: var(--sl-color-primary-600);
   z-index: 1;
 }
 
 .code-block__button:focus-visible {
   outline: none;
-  color: var(--sl-color-primary-600);
-  border-color: var(--sl-color-primary-400);
-  border-right-color: transparent;
-  background-color: var(--sl-color-primary-50);
-  box-shadow: 0 0 0 1px var(--sl-color-primary-400), var(--sl-focus-ring);
+  outline: var(--sl-focus-ring);
   z-index: 2;
 }
 
@@ -210,7 +206,8 @@
 }
 
 .markdown-section .docsify-copy-code-button:focus-visible {
-  box-shadow: var(--sl-focus-ring);
+  outline: var(--sl-focus-ring);
+  outline-offset: var(--sl-focus-ring-offset);
 }
 
 .markdown-section .docsify-copy-code-button:active {

docs/assets/plugins/code-block/code-block.js

@@ -1,3 +1,5 @@
+/* global Prism */
+
 (() => {
   const reactVersion = '17.0.2';
   let flavor = getFlavor();
@@ -61,14 +63,9 @@
     document.body.classList.toggle('flavor-react', flavor === 'react');
   }
 
-  function wrap(el, wrapper) {
-    el.parentNode.insertBefore(wrapper, el);
-    wrapper.appendChild(el);
-  }
-
-  window.$docsify.plugins.push((hook, vm) => {
+  window.$docsify.plugins.push(hook => {
     // Convert code blocks to previews
-    hook.afterEach(function (html, next) {
+    hook.afterEach((html, next) => {
       const domParser = new DOMParser();
       const doc = domParser.parseFromString(html, 'text/html');
 
@@ -111,7 +108,7 @@
         </button>
       `;
 
-      [...doc.querySelectorAll('code[class^="lang-"]')].map(code => {
+      [...doc.querySelectorAll('code[class^="lang-"]')].forEach(code => {
         if (code.classList.contains('preview')) {
           const isExpanded = code.classList.contains('expanded');
           const pre = code.closest('pre');
@@ -119,12 +116,6 @@
           const toggleId = `code-block-toggle-${count}`;
           const reactPre = getAdjacentExample('react', pre);
           const hasReact = reactPre !== null;
-          const examples = [
-            {
-              name: 'HTML',
-              codeBlock: pre
-            }
-          ];
 
           pre.setAttribute('data-lang', pre.getAttribute('data-lang').replace(/ preview$/, ''));
           pre.setAttribute('aria-labelledby', toggleId);
@@ -155,8 +146,6 @@
               </div>
 
               <div class="code-block__buttons">
-                ${hasReact ? ` ${htmlButton} ${reactButton} ` : ''}
-
                 <button
                   type="button"
                   class="code-block__button code-block__toggle"
@@ -176,13 +165,15 @@
                   </svg>
                 </button>
 
+                ${hasReact ? ` ${htmlButton} ${reactButton} ` : ''}
+
                 ${!code.classList.contains('no-codepen') ? codePenButton : ''}
               </div>
             </div>
           `;
 
           pre.replaceWith(domParser.parseFromString(codeBlock, 'text/html').body);
-          if (reactPre) reactPre.remove();
+          reactPre?.remove();
 
           count++;
         }
@@ -201,75 +192,85 @@
 
     // Horizontal resizing
     hook.doneEach(() => {
-      [...document.querySelectorAll('.code-block__preview')].map(preview => {
+      [...document.querySelectorAll('.code-block__preview')].forEach(preview => {
         const resizer = preview.querySelector('.code-block__resizer');
         let startX;
         let startWidth;
 
-        const dragStart = event => {
+        function dragStart(event) {
           startX = event.changedTouches ? event.changedTouches[0].pageX : event.clientX;
           startWidth = parseInt(document.defaultView.getComputedStyle(preview).width, 10);
           preview.classList.add('code-block__preview--dragging');
           event.preventDefault();
-          document.documentElement.addEventListener('mousemove', dragMove, false);
-          document.documentElement.addEventListener('touchmove', dragMove, false);
-          document.documentElement.addEventListener('mouseup', dragStop, false);
-          document.documentElement.addEventListener('touchend', dragStop, false);
-        };
+          document.documentElement.addEventListener('mousemove', dragMove);
+          document.documentElement.addEventListener('touchmove', dragMove);
+          document.documentElement.addEventListener('mouseup', dragStop);
+          document.documentElement.addEventListener('touchend', dragStop);
+        }
 
-        const dragMove = event => {
+        function dragMove(event) {
           setWidth(startWidth + (event.changedTouches ? event.changedTouches[0].pageX : event.pageX) - startX);
-        };
+        }
 
-        const dragStop = event => {
+        function dragStop() {
           preview.classList.remove('code-block__preview--dragging');
-          document.documentElement.removeEventListener('mousemove', dragMove, false);
-          document.documentElement.removeEventListener('touchmove', dragMove, false);
-          document.documentElement.removeEventListener('mouseup', dragStop, false);
-          document.documentElement.removeEventListener('touchend', dragStop, false);
-        };
+          document.documentElement.removeEventListener('mousemove', dragMove);
+          document.documentElement.removeEventListener('touchmove', dragMove);
+          document.documentElement.removeEventListener('mouseup', dragStop);
+          document.documentElement.removeEventListener('touchend', dragStop);
+        }
 
-        const setWidth = width => (preview.style.width = width + 'px');
+        function setWidth(width) {
+          preview.style.width = `${width}px`;
+        }
 
         resizer.addEventListener('mousedown', dragStart);
-        resizer.addEventListener('touchstart', dragStart);
+        resizer.addEventListener('touchstart', dragStart, { passive: true });
       }, false);
     });
   });
 
   // Toggle source mode
   document.addEventListener('click', event => {
-    const button = event.target.closest('button');
+    const button = event.target.closest('.code-block__button');
     const codeBlock = button?.closest('.code-block');
 
     if (button?.classList.contains('code-block__button--html')) {
+      // Show HTML
       setFlavor('html');
+      toggleSource(codeBlock, true);
     } else if (button?.classList.contains('code-block__button--react')) {
+      // Show React
       setFlavor('react');
+      toggleSource(codeBlock, true);
+    } else if (button?.classList.contains('code-block__toggle')) {
+      // Toggle source
+      toggleSource(codeBlock);
     } else {
       return;
     }
 
     // Update flavor buttons
-    [...document.querySelectorAll('.code-block')].map(codeBlock => {
-      codeBlock
-        .querySelector('.code-block__button--html')
-        ?.classList.toggle('code-block__button--selected', flavor === 'html');
-      codeBlock
-        .querySelector('.code-block__button--react')
-        ?.classList.toggle('code-block__button--selected', flavor === 'react');
+    [...document.querySelectorAll('.code-block')].forEach(cb => {
+      cb.querySelector('.code-block__button--html')?.classList.toggle(
+        'code-block__button--selected',
+        flavor === 'html'
+      );
+      cb.querySelector('.code-block__button--react')?.classList.toggle(
+        'code-block__button--selected',
+        flavor === 'react'
+      );
     });
   });
 
-  // Expand and collapse code blocks
-  document.addEventListener('click', event => {
-    const toggle = event.target.closest('.code-block__toggle');
+  function toggleSource(codeBlock, force) {
+    const toggle = codeBlock.querySelector('.code-block__toggle');
+
     if (toggle) {
-      const codeBlock = event.target.closest('.code-block');
-      codeBlock.classList.toggle('code-block--expanded');
+      codeBlock.classList.toggle('code-block--expanded', force === undefined ? undefined : force);
       event.target.setAttribute('aria-expanded', codeBlock.classList.contains('code-block--expanded'));
     }
-  });
+  }
 
   // Show pulse when copying
   document.addEventListener('click', event => {
@@ -310,8 +311,7 @@
       if (!isReact) {
         htmlTemplate =
           `<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${version}/dist/shoelace.js"></script>\n` +
-          '\n' +
-          htmlExample;
+          `\n${htmlExample}`;
         jsTemplate = '';
       }
 
@@ -322,13 +322,11 @@
           `import React from 'https://cdn.skypack.dev/react@${reactVersion}';\n` +
           `import ReactDOM from 'https://cdn.skypack.dev/react-dom@${reactVersion}';\n` +
           `import { setBasePath } from 'https://cdn.skypack.dev/@shoelace-style/shoelace@${version}/dist/utilities/base-path';\n` +
-          '\n' +
+          `\n` +
           `// Set the base path for Shoelace assets\n` +
           `setBasePath('https://cdn.skypack.dev/@shoelace-style/shoelace@${version}/dist/')\n` +
-          '\n' +
-          convertModuleLinks(reactExample) +
-          '\n' +
-          '\n' +
+          `\n${convertModuleLinks(reactExample)}\n` +
+          `\n` +
           `ReactDOM.render(<App />, document.getElementById('root'));`;
       }
 

docs/assets/plugins/metadata/metadata.js

@@ -7,6 +7,7 @@
 
   function createPropsTable(props) {
     const table = document.createElement('table');
+    table.classList.add('metadata-table');
     table.innerHTML = `
       <thead>
         <tr>
@@ -29,7 +30,7 @@
             } else if (isAttributeDifferent) {
               attributeInfo = `
                 <br>
-                <sl-tooltip content="This attribute is different than the property">
+                <sl-tooltip content="This attribute is different from its property">
                   <small>
                     <code class="nowrap">
                       ${escapeHtml(prop.attribute)}
@@ -48,7 +49,7 @@
                   ${escapeHtml(prop.description)}
                 </td>
                 <td style="text-align: center;">${
-                  prop.reflects ? '<sl-icon label="yes" name="check"></sl-icon>' : ''
+                  prop.reflects ? '<sl-icon label="yes" name="check-lg"></sl-icon>' : ''
                 }</td>
                 <td>${prop.type?.text ? `<code>${escapeHtml(prop.type?.text || '')}</code>` : '-'}</td>
                 <td>${prop.default ? `<code>${escapeHtml(prop.default)}</code>` : '-'}</td>
@@ -56,7 +57,18 @@
             `;
           })
           .join('')}
-      </tbody>
+
+          <tr>
+            <td class="nowrap"><code>updateComplete</code></td>
+            <td>
+              A read-only promise that resolves when the component has
+              <a href="/getting-started/usage?id=component-rendering-and-updating">finished updating</a>.
+            </td>
+            <td></td>
+            <td></td>
+            <td></td>
+          </tr>
+        </tbody>
     `;
 
     return table.outerHTML;
@@ -64,6 +76,7 @@
 
   function createEventsTable(events) {
     const table = document.createElement('table');
+    table.classList.add('metadata-table');
     table.innerHTML = `
       <thead>
         <tr>
@@ -94,6 +107,7 @@
 
   function createMethodsTable(methods) {
     const table = document.createElement('table');
+    table.classList.add('metadata-table');
     table.innerHTML = `
       <thead>
         <tr>
@@ -107,14 +121,14 @@
           .map(
             method => `
               <tr>
-                <td class="nowrap"><code>${escapeHtml(method.name)}</code></td>
+                <td class="nowrap"><code>${escapeHtml(method.name)}()</code></td>
                 <td>${escapeHtml(method.description)}</td>
                 <td>
                   ${
                     method.parameters?.length
                       ? `
                         <code>${escapeHtml(
-                          method.parameters.map(param => `${param.name}: ${param.type.text}`).join(', ')
+                          method.parameters.map(param => `${param.name}: ${param.type?.text || ''}`).join(', ')
                         )}</code>
                       `
                       : '-'
@@ -132,6 +146,7 @@
 
   function createSlotsTable(slots) {
     const table = document.createElement('table');
+    table.classList.add('metadata-table');
     table.innerHTML = `
       <thead>
         <tr>
@@ -158,11 +173,13 @@
 
   function createCustomPropertiesTable(styles) {
     const table = document.createElement('table');
+    table.classList.add('metadata-table');
     table.innerHTML = `
       <thead>
         <tr>
           <th>Name</th>
           <th>Description</th>
+          <th>Default</th>
         </tr>
       </thead>
       <tbody>
@@ -170,8 +187,9 @@
           .map(
             style => `
               <tr>
-                <td><code>${escapeHtml(style.name)}</code></td>
+                <td class="nowrap"><code>${escapeHtml(style.name)}</code></td>
                 <td>${escapeHtml(style.description)}</td>
+                <td>${style.default ? `<code>${escapeHtml(style.default)}</code>` : ''}</td>
               </tr>
             `
           )
@@ -184,6 +202,7 @@
 
   function createPartsTable(parts) {
     const table = document.createElement('table');
+    table.classList.add('metadata-table');
     table.innerHTML = `
       <thead>
         <tr>
@@ -210,6 +229,7 @@
 
   function createAnimationsTable(animations) {
     const table = document.createElement('table');
+    table.classList.add('metadata-table');
     table.innerHTML = `
       <thead>
         <tr>
@@ -238,23 +258,23 @@
     const ul = document.createElement('ul');
     const dependencies = [];
 
-    // Recursively fetch subdependencies
+    // Recursively fetch sub-dependencies
     function getDependencies(tag) {
       const component = allComponents.find(c => c.tagName === tag);
       if (!component || !Array.isArray(component.dependencies)) {
-        return [];
+        return;
       }
 
-      component.dependencies?.map(tag => {
-        if (!dependencies.includes(tag)) {
-          dependencies.push(tag);
+      component.dependencies?.forEach(dependentTag => {
+        if (!dependencies.includes(dependentTag)) {
+          dependencies.push(dependentTag);
         }
-        getDependencies(tag);
+        getDependencies(dependentTag);
       });
     }
 
     getDependencies(targetComponent);
-    dependencies.sort().map(tag => {
+    dependencies.sort().forEach(tag => {
       const li = document.createElement('li');
       li.innerHTML = `<code>&lt;${tag}&gt;</code>`;
       ul.appendChild(li);
@@ -264,19 +284,24 @@
   }
 
   function escapeHtml(html) {
-    return (html + '')
+    if (!html) {
+      return '';
+    }
+    return html
+      .toString()
       .replace(/&/g, '&amp;')
       .replace(/</g, '&lt;')
       .replace(/>/g, '&gt;')
       .replace(/"/g, '&quot;')
       .replace(/'/g, '&apos;')
+      .replace(/\[(.*?)\]\((.*?)\)/g, '<a href="$2" rel="noopener noreferrer" target="_blank">$1</a>')
       .replace(/`(.*?)`/g, '<code>$1</code>');
   }
 
   function getAllComponents(metadata) {
     const allComponents = [];
-    metadata.modules?.map(module => {
-      module.declarations?.map(declaration => {
+    metadata.modules?.forEach(module => {
+      module.declarations?.forEach(declaration => {
         if (declaration.customElement) {
           // Generate the dist path based on the src path and attach it to the component
           declaration.path = module.path.replace(/^src\//, 'dist/').replace(/\.ts$/, '.js');
@@ -297,8 +322,8 @@
     throw new Error('Docsify must be loaded before installing this plugin.');
   }
 
-  window.$docsify.plugins.push((hook, vm) => {
-    hook.mounted(async function () {
+  window.$docsify.plugins.push(hook => {
+    hook.mounted(async () => {
       const metadata = await customElements;
       const target = document.querySelector('.app-name');
 
@@ -319,7 +344,7 @@
           <sl-icon slot="prefix" name="heart"></sl-icon> Sponsor
         </sl-button>
         <sl-button size="small" class="repo-button repo-button--github" href="https://github.com/shoelace-style/shoelace/stargazers" target="_blank">
-          <sl-icon slot="prefix" name="github"></sl-icon> <span class="github-star-count">Star</span>
+          <sl-icon slot="prefix" name="github"></sl-icon> Star
         </sl-button>
         <sl-button size="small" class="repo-button repo-button--twitter" href="https://twitter.com/shoelace_style" target="_blank">
           <sl-icon slot="prefix" name="twitter"></sl-icon> Follow
@@ -328,7 +353,7 @@
       target.appendChild(buttons);
     });
 
-    hook.beforeEach(async function (content, next) {
+    hook.beforeEach(async (content, next) => {
       const metadata = await customElements;
 
       // Replace %VERSION% placeholders
@@ -340,20 +365,28 @@
         let result = '';
 
         if (!component) {
-          console.error('Component not found in metadata: ' + tag);
+          console.error(`Component not found in metadata: ${tag}`);
           return next(content);
         }
 
         let badgeType = 'neutral';
-        if (component.status === 'stable') badgeType = 'primary';
-        if (component.status === 'experimental') badgeType = 'warning';
-        if (component.status === 'planned') badgeType = 'neutral';
-        if (component.status === 'deprecated') badgeType = 'danger';
+        if (component.status === 'stable') {
+          badgeType = 'primary';
+        }
+        if (component.status === 'experimental') {
+          badgeType = 'warning';
+        }
+        if (component.status === 'planned') {
+          badgeType = 'neutral';
+        }
+        if (component.status === 'deprecated') {
+          badgeType = 'danger';
+        }
 
         result += `
           <div class="component-header">
             <div class="component-header__tag">
-              <code>&lt;${component.tagName}&gt; | ${component.name}</code>
+              <code>&lt;${component.tagName}&gt; | ${component.title ?? component.name}</code>
             </div>
 
             <div class="component-header__info">
@@ -365,6 +398,10 @@
                 ${component.status}
               </sl-badge>
             </div>
+
+            <div class="component-header__summary">
+              ${component.summary ? `<p>${marked(component.summary)}</p>` : ''}
+            </div>
           </div>
         `;
 
@@ -377,7 +414,7 @@
         let result = '';
 
         if (!component) {
-          console.error('Component not found in metadata: ' + tag);
+          console.error(`Component not found in metadata: ${tag}`);
           return next(content);
         }
 
@@ -409,7 +446,7 @@
             To import this component from [the CDN](https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace) using a script tag:
 
             \`\`\`html
-            <script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${metadata.package.version}/${component.path}"></script>
+            <script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${metadata.package.version}/dist/${component.path}"></script>
             \`\`\`
             </sl-tab-panel>
 
@@ -417,14 +454,14 @@
             To import this component from [the CDN](https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace) using a JavaScript import:
 
             \`\`\`js
-            import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${metadata.package.version}/${component.path}';
+            import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${metadata.package.version}/dist/${component.path}';
             \`\`\`
             </sl-tab-panel>
 
             <sl-tab-panel name="bundler">\n
             To import this component using [a bundler](/getting-started/installation#bundling):
             \`\`\`js
-            import '@shoelace-style/shoelace/${component.path}';
+            import '@shoelace-style/shoelace/dist/${component.path}';
             \`\`\`
             </sl-tab-panel>
 
@@ -435,39 +472,27 @@
             \`\`\`
             </sl-tab-panel>
             </sl-tab-group>
-          `;
-        }
 
-        if (props?.length) {
-          result += `
-            ## Properties
-            ${createPropsTable(props)}
-          `;
-        }
+            <div class="sponsor-callout">
+              <p>
+                Shoelace is designed, developed, and maintained by <a href="https://twitter.com/claviska" target="_blank">Cory LaViska</a>.
+                Please sponsor my open source work on GitHub. Your support will keep this project alive and growing!
+              </p>
 
-        if (component.events?.length) {
-          result += `
-            ## Events
-            ${createEventsTable(component.events)}
-          `;
-        }
+              <p>
+                <sl-button class="repo-button repo-button--sponsor" href="https://github.com/sponsors/claviska" target="_blank">
+                  <sl-icon slot="prefix" name="heart"></sl-icon> Sponsor <span class="sponsor-callout__secondary-label">Development</span>
+                </sl-button>
 
-        if (methods?.length) {
-          result += `
-            ## Methods
+                <sl-button class="repo-button repo-button--github" href="https://github.com/shoelace-style/shoelace/stargazers" target="_blank">
+                  <sl-icon slot="prefix" name="github"></sl-icon> Star <span class="sponsor-callout__secondary-label">on GitHub</span>
+                </sl-button>
 
-            <p data-flavor="html">
-              Methods can be called by obtaining a reference to the element and calling
-              <code>el.methodName()</code>.
-            </p>
-
-
-            <p data-flavor="react">
-              Methods can be called by obtaining a <code>ref</code> to the element and calling
-              <code>ref.current.methodName()</code>.
-            </p>
-
-            ${createMethodsTable(methods)}
+                <sl-button class="repo-button repo-button--twitter" href="https://twitter.com/shoelace_style" target="_blank">
+                  <sl-icon slot="prefix" name="twitter"></sl-icon> Follow <span class="sponsor-callout__secondary-label">on Twitter</span>
+                </sl-button>
+              </p>
+            </div>
           `;
         }
 
@@ -475,6 +500,36 @@
           result += `
             ## Slots
             ${createSlotsTable(component.slots)}
+
+            _Learn more about [using slots](/getting-started/usage#slots)._
+          `;
+        }
+
+        if (props?.length) {
+          result += `
+            ## Attributes & Properties
+            ${createPropsTable(props)}
+
+            _Learn more about [attributes and properties](/getting-started/usage#properties)._
+          `;
+        }
+
+        if (component.events?.length) {
+          result += `
+            ## Events
+            ${createEventsTable(component.events)}
+
+            _Learn more about [listening to events](/getting-started/usage#events)._
+          `;
+        }
+
+        if (methods?.length) {
+          result += `
+            ## Methods
+
+            ${createMethodsTable(methods)}
+
+            _Learn more about [calling methods](/getting-started/usage#methods)._
           `;
         }
 
@@ -482,6 +537,8 @@
           result += `
             ## CSS Custom Properties
             ${createCustomPropertiesTable(component.cssProperties)}
+
+            _Learn more about [customizing CSS Custom Properties](/getting-started/customizing#custom-properties)._
           `;
         }
 
@@ -489,6 +546,8 @@
           result += `
             ## CSS Parts
             ${createPartsTable(component.cssParts)}
+
+            _Learn more about [customizing CSS Parts](/getting-started/customizing#component-parts)._
           `;
         }
 
@@ -497,7 +556,7 @@
             ## Animations
             ${createAnimationsTable(component.animations)}
 
-            Learn how to [customize animations](/getting-started/customizing#animations).
+            _Learn more about [customizing animations](/getting-started/customizing#animations)._
           `;
         }
 
@@ -505,7 +564,7 @@
           result += `
             ## Dependencies
 
-            This component imports the following dependencies.
+            This component automatically imports the following dependencies.
 
             ${createDependenciesList(component.tagName, getAllComponents(metadata))}
           `;
@@ -519,11 +578,11 @@
     });
 
     // Wrap tables so we can scroll them horizontally when needed
-    hook.doneEach(function () {
+    hook.doneEach(() => {
       const content = document.querySelector('.content');
       const tables = [...content.querySelectorAll('table')];
 
-      tables.map(table => {
+      tables.forEach(table => {
         table.outerHTML = `
           <div class="table-wrapper">
             ${table.outerHTML}

docs/assets/plugins/scroll-position/scroll-position.js

@@ -7,7 +7,7 @@
   // Docsify generates pages dynamically and asynchronously, so when a reload happens, the scroll position can't be
   // be restored immediately. This plugin waits until Docsify loads the page and then restores it.
   //
-  window.$docsify.plugins.push((hook, vm) => {
+  window.$docsify.plugins.push(hook => {
     hook.ready(() => {
       // Restore
       const scrollTop = sessionStorage.getItem('bs-scroll');
@@ -16,7 +16,7 @@
       }
 
       // Remember
-      document.addEventListener('scroll', event => {
+      document.addEventListener('scroll', () => {
         sessionStorage.setItem('bs-scroll', document.documentElement.scrollTop);
       });
     });

docs/assets/plugins/search/search.css

@@ -8,6 +8,7 @@ body.site-search-visible {
 
 .sidebar .search-box kbd {
   margin-top: 2px;
+  margin-right: 1rem;
 }
 
 /* Site search */
@@ -177,3 +178,15 @@ body.site-search-visible {
     display: none;
   }
 }
+
+/* Forced colors mode */
+@media (forced-colors: active) {
+  .site-search__panel {
+    border: solid 1px var(--sl-color-neutral-0);
+  }
+
+  .site-search__results li[aria-selected='true'] a {
+    outline: dashed 1px SelectedItem;
+    outline-offset: -1px;
+  }
+}

docs/assets/plugins/search/search.js

@@ -1,21 +1,17 @@
+/* global lunr */
 (() => {
   if (!window.$docsify) {
     throw new Error('Docsify must be loaded before installing this plugin.');
   }
 
-  window.$docsify.plugins.push((hook, vm) => {
+  window.$docsify.plugins.push(hook => {
     // Append the search box to the sidebar
-    hook.mounted(function () {
+    hook.mounted(() => {
       const appName = document.querySelector('.sidebar .app-name');
       const searchBox = document.createElement('div');
       searchBox.classList.add('search-box');
       searchBox.innerHTML = `
-        <sl-input
-          type="search"
-          placeholder="Search"
-          clearable
-          pill
-        >
+        <sl-input type="search" placeholder="Search" pill>
           <sl-icon slot="prefix" name="search"></sl-icon>
           <kbd slot="suffix" title="Press / to search">/</kbd>
         </sl-input>
@@ -51,12 +47,21 @@
     siteSearch.hidden = true;
     siteSearch.innerHTML = `
       <div class="site-search__overlay"></div>
-      <div class="site-search__panel">
+      <div
+        id="site-search-panel"
+        class="site-search__panel"
+        role="combobox"
+        aria-expanded="false"
+        aria-owns="site-search-results"
+        aria-activedescendant=""
+      >
         <header class="site-search__header">
           <sl-input
             class="site-search__input"
             type="search"
             placeholder="Search this site"
+            aria-autocomplete="list"
+            aria-controls="site-search-results"
             size="large"
             clearable
           >
@@ -64,7 +69,13 @@
           </sl-input>
         </header>
         <div class="site-search__body">
-          <ul class="site-search__results"></ul>
+          <ul
+            id="site-search-results"
+            class="site-search__results"
+            role="listbox"
+            aria-labelledby="site-search-panel"
+          >
+          </ul>
           <div class="site-search__empty">No results found.</div>
         </div>
         <footer class="site-search__footer">
@@ -76,7 +87,6 @@
     `;
     document.body.append(siteSearch);
 
-    const searchButtons = [...document.querySelectorAll('[data-site-search]')];
     const overlay = siteSearch.querySelector('.site-search__overlay');
     const panel = siteSearch.querySelector('.site-search__panel');
     const input = siteSearch.querySelector('.site-search__input');
@@ -89,7 +99,7 @@
     let map;
 
     // Load search data
-    const searchData = fetch('../../../search.json')
+    fetch('../../../search.json')
       .then(res => res.json())
       .then(data => {
         searchIndex = lunr.Index.load(data.searchIndex);
@@ -100,7 +110,7 @@
       isShowing = true;
       document.body.classList.add('site-search-visible');
       siteSearch.hidden = false;
-      input.focus();
+      requestAnimationFrame(() => input.focus());
       updateResults();
 
       await Promise.all([
@@ -203,16 +213,17 @@
         }
 
         // Update the selected item
-        items.map(item => {
+        items.forEach(item => {
           if (item === nextEl) {
+            const a = nextEl.querySelector('a');
+            panel.setAttribute('aria-activedescendant', a.id);
+
             item.setAttribute('aria-selected', 'true');
             nextEl.scrollIntoView({ block: 'nearest' });
           } else {
             item.setAttribute('aria-selected', 'false');
           }
         });
-
-        return;
       }
     }
 
@@ -221,34 +232,47 @@
         await searchIndex;
 
         const hasQuery = query.length > 0;
-        let matches = hasQuery ? searchIndex.search(`${query}`) : [];
-
-        // Fall back to a fuzzy search if no matches are found
-        if (matches.length === 0 && hasQuery) {
-          matches = searchIndex.search(`${query}~2`);
-        }
-
-        let hasResults = hasQuery && matches.length > 0;
+        const searchTokens = query
+          .split(' ')
+          .map((term, index, arr) => `${term}${index === arr.length - 1 ? `* ${term}~1` : '~1'}`)
+          .join(' ');
+        const matches = hasQuery ? searchIndex.search(`${query} ${searchTokens}`) : [];
+        const hasResults = hasQuery && matches.length > 0;
         siteSearch.classList.toggle('site-search--has-results', hasQuery && hasResults);
         siteSearch.classList.toggle('site-search--no-results', hasQuery && !hasResults);
         panel.setAttribute('aria-expanded', hasQuery && hasResults ? 'true' : 'false');
 
         results.innerHTML = '';
 
-        matches.map((match, index) => {
+        matches.forEach((match, index) => {
           const page = map[match.ref];
           const li = document.createElement('li');
           const a = document.createElement('a');
           let icon = 'file-text';
 
-          if (page.url.includes('getting-started/')) icon = 'lightbulb';
-          if (page.url.includes('resources/')) icon = 'book';
-          if (page.url.includes('components/')) icon = 'puzzle';
-          if (page.url.includes('tokens/')) icon = 'palette2';
-          if (page.url.includes('utilities/')) icon = 'wrench';
-          if (page.url.includes('tutorials/')) icon = 'joystick';
+          a.setAttribute('role', 'option');
+          a.setAttribute('id', `search-result-item-${match.ref}`);
 
-          a.href = $docsify.routerMode === 'hash' ? `/#/${page.url}` : `/${page.url}`;
+          if (page.url.includes('getting-started/')) {
+            icon = 'lightbulb';
+          }
+          if (page.url.includes('resources/')) {
+            icon = 'book';
+          }
+          if (page.url.includes('components/')) {
+            icon = 'puzzle';
+          }
+          if (page.url.includes('tokens/')) {
+            icon = 'palette2';
+          }
+          if (page.url.includes('utilities/')) {
+            icon = 'wrench';
+          }
+          if (page.url.includes('tutorials/')) {
+            icon = 'joystick';
+          }
+
+          a.href = window.$docsify.routerMode === 'hash' ? `/#/${page.url}` : `/${page.url}`;
           a.innerHTML = `
             <div class="site-search__result-icon">
               <sl-icon name="${icon}" aria-hidden="true"></sl-icon>
@@ -271,9 +295,12 @@
 
     // Show the search panel slash is pressed outside of a form element
     document.addEventListener('keydown', event => {
+      const isSlash = event.key === '/';
+      const isCtrlK = (event.metaKey || event.ctrlKey) && event.key === 'k';
+
       if (
         !isShowing &&
-        event.key === '/' &&
+        (isSlash || isCtrlK) &&
         !event.composedPath().some(el => ['input', 'textarea'].includes(el?.tagName?.toLowerCase()))
       ) {
         event.preventDefault();

docs/assets/plugins/theme-picker/theme-picker.js

@@ -3,8 +3,8 @@
     throw new Error('Docsify must be loaded before installing this plugin.');
   }
 
-  window.$docsify.plugins.push((hook, vm) => {
-    hook.mounted(function () {
+  window.$docsify.plugins.push(hook => {
+    hook.mounted(() => {
       function getTheme() {
         return localStorage.getItem('theme') || 'auto';
       }
@@ -12,9 +12,8 @@
       function isDark() {
         if (theme === 'auto') {
           return window.matchMedia('(prefers-color-scheme: dark)').matches;
-        } else {
-          return theme === 'dark';
         }
+        return theme === 'dark';
       }
 
       function setTheme(newTheme) {
@@ -48,10 +47,10 @@
         </sl-button>
         <sl-menu>
           <sl-menu-label>Toggle <kbd>\\</kbd></sl-menu-label>
-          <sl-menu-item value="light">Light</sl-menu-item>
-          <sl-menu-item value="dark">Dark</sl-menu-item>
+          <sl-menu-item type="checkbox" value="light">Light</sl-menu-item>
+          <sl-menu-item type="checkbox" value="dark">Dark</sl-menu-item>
           <sl-divider></sl-divider>
-          <sl-menu-item value="auto">Auto</sl-menu-item>
+          <sl-menu-item type="checkbox" value="auto">Auto</sl-menu-item>
         </sl-menu>
       `;
       document.querySelector('.sidebar-toggle').insertAdjacentElement('afterend', dropdown);
@@ -62,7 +61,7 @@
       menu.addEventListener('sl-select', event => setTheme(event.detail.item.value));
 
       // Update the theme when the preference changes
-      window.matchMedia('(prefers-color-scheme: dark)').addListener(event => setTheme(theme));
+      window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => setTheme(theme));
 
       // Toggle themes when pressing backslash
       document.addEventListener('keydown', event => {
@@ -76,7 +75,7 @@
         }
       });
 
-      // Set the intial theme and sync the UI
+      // Set the initial theme and sync the UI
       setTheme(theme);
     });
   });

docs/assets/styles/docs.css

@@ -8,6 +8,17 @@ html {
   box-sizing: inherit;
 }
 
+/* Show custom elements only after they're registered */
+:not(:defined),
+:not(:defined) * {
+  opacity: 0;
+}
+
+:defined {
+  opacity: 1;
+  transition: 0.1s opacity;
+}
+
 body {
   font-family: var(--sl-font-sans);
   font-size: var(--sl-font-size-medium);
@@ -50,6 +61,8 @@ strong {
 }
 
 .sidebar-buttons {
+  display: flex;
+  justify-content: space-between;
   text-align: center;
   margin-top: 0;
 }
@@ -74,8 +87,8 @@ strong {
 }
 
 .sidebar-toggle:focus {
-  outline: none;
-  box-shadow: var(--sl-focus-ring);
+  outline: var(--sl-focus-ring);
+  outline-offset: var(--sl-focus-ring-offset);
 }
 
 .sidebar-toggle span:last-child {
@@ -290,10 +303,6 @@ strong {
   padding: 2px 4px;
 }
 
-.markdown-section tr:nth-child(2n) code {
-  background-color: var(--sl-color-neutral-100);
-}
-
 kbd,
 .markdown-section kbd {
   font-family: var(--sl-font-mono);
@@ -316,7 +325,7 @@ kbd,
   display: block;
   background: none;
   border-radius: 0;
-  color: var(--sl-color-neutral-800);
+  color: var(--sl-color-neutral-900);
   padding: var(--sl-spacing-medium);
   overflow: auto;
   hyphens: none;
@@ -331,11 +340,11 @@ kbd,
 .markdown-section pre .token.doctype,
 .markdown-section pre .token.cdata,
 .markdown-section pre .token.operator {
-  color: var(--sl-color-neutral-600);
+  color: var(--sl-color-neutral-700);
 }
 
 .markdown-section pre .token.punctuation {
-  color: var(--sl-color-neutral-600);
+  color: var(--sl-color-neutral-700);
 }
 
 .namespace {
@@ -346,12 +355,12 @@ kbd,
 .markdown-section pre .token.keyword,
 .markdown-section pre .token.tag,
 .markdown-section pre .token.url {
-  color: var(--sl-color-blue-600);
+  color: var(--sl-color-sky-800);
 }
 
 .markdown-section pre .token.symbol,
 .markdown-section pre .token.deleted {
-  color: var(--sl-color-pink-600);
+  color: var(--sl-color-pink-700);
 }
 
 .markdown-section pre .token.boolean,
@@ -362,7 +371,7 @@ kbd,
 .markdown-section pre .token.char,
 .markdown-section pre .token.builtin,
 .markdown-section pre .token.inserted {
-  color: var(--sl-color-emerald-600);
+  color: var(--sl-color-emerald-700);
 }
 
 .markdown-section pre .token.atrule,
@@ -375,11 +384,11 @@ kbd,
 .markdown-section pre .token.function,
 .markdown-section pre .token.class-name,
 .markdown-section pre .token.regex {
-  color: var(--sl-color-orange-600);
+  color: var(--sl-color-orange-700);
 }
 
 .markdown-section pre .token.important {
-  color: var(--sl-color-red-600);
+  color: var(--sl-color-red-700);
 }
 
 .markdown-section pre .token.important,
@@ -412,7 +421,7 @@ kbd,
 }
 
 .markdown-section tr:nth-child(2n) {
-  background: var(--sl-color-neutral-50);
+  background: transparent;
 }
 
 .markdown-section th {
@@ -426,6 +435,7 @@ kbd,
   border-bottom: solid 1px var(--sl-color-neutral-200);
   border-left: none;
   border-right: none;
+  padding: 0.75rem 0.5rem;
 }
 
 .markdown-section table .nowrap {
@@ -437,6 +447,10 @@ kbd,
   cursor: help;
 }
 
+.markdown-section .metadata-table {
+  margin-bottom: 0rem;
+}
+
 /* Iframes */
 .markdown-section iframe {
   border: none;
@@ -487,14 +501,26 @@ kbd,
 .markdown-section p.tip code,
 .markdown-section p.warn code {
   background-color: var(--sl-color-neutral-100);
+  white-space: nowrap;
+}
+
+/* Sponsorship callouts */
+.sponsor-callout {
+  background: var(--sl-color-warning-100);
+  border-left: solid 3px var(--sl-color-warning-300);
+  border-radius: var(--sl-border-radius-medium);
+  padding: 0.5rem 1.5rem;
+}
+
+@media screen and (max-width: 950px) {
+  .sponsor-callout__secondary-label {
+    display: none;
+  }
 }
 
 /* Component headers */
 .component-header {
-  border-bottom: solid 1px var(--sl-color-neutral-200);
-  padding-bottom: 2rem;
   margin-top: -1rem;
-  margin-bottom: 2rem;
 }
 
 .component-header__tag {
@@ -503,6 +529,13 @@ kbd,
   margin: 0.75rem 0 0.25rem 0;
 }
 
+.component-header__summary {
+  font-size: var(--sl-font-size-large);
+  line-height: 1.6;
+  border-top: solid 1px var(--sl-color-neutral-200);
+  margin-top: 2rem;
+}
+
 .markdown-section .component-header__tag code {
   background: none;
   color: var(--sl-color-neutral-600);
@@ -515,12 +548,6 @@ kbd,
   margin-bottom: 0.5rem;
 }
 
-/* Lead sentences that occur immediately after the header */
-.component-header + p {
-  font-size: var(--sl-font-size-large);
-  line-height: 1.6;
-}
-
 /* Repo buttons */
 .repo-button--sponsor sl-icon {
   color: var(--sl-color-pink-600);
@@ -583,7 +610,7 @@ body[data-page^='/tokens/'] .table-wrapper td:first-child code {
   background: var(--sl-color-primary-600);
 }
 
-/* Elevation dmeo */
+/* Elevation demo */
 .elevation-demo {
   background: transparent;
   border-radius: 3px;

docs/components/alert.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-alert]
 
-Alerts are used to display important messages inline or as toast notifications.
-
 ```html preview
 <sl-alert open>
   <sl-icon slot="icon" name="info-circle"></sl-icon>
@@ -33,40 +31,40 @@ Set the `variant` attribute to change the alert's variant.
 ```html preview
 <sl-alert variant="primary" open>
   <sl-icon slot="icon" name="info-circle"></sl-icon>
-  <strong>This is super informative</strong><br>
+  <strong>This is super informative</strong><br />
   You can tell by how pretty the alert is.
 </sl-alert>
 
-<br>
+<br />
 
 <sl-alert variant="success" open>
   <sl-icon slot="icon" name="check2-circle"></sl-icon>
-  <strong>Your changes have been saved</strong><br>
+  <strong>Your changes have been saved</strong><br />
   You can safely exit the app now.
 </sl-alert>
 
-<br>
+<br />
 
 <sl-alert variant="neutral" open>
   <sl-icon slot="icon" name="gear"></sl-icon>
-  <strong>Your settings have been updated</strong><br>
+  <strong>Your settings have been updated</strong><br />
   Settings will take affect on next login.
 </sl-alert>
 
-<br>
+<br />
 
 <sl-alert variant="warning" open>
   <sl-icon slot="icon" name="exclamation-triangle"></sl-icon>
-  <strong>Your session has ended</strong><br>
+  <strong>Your session has ended</strong><br />
   Please login again to continue.
 </sl-alert>
 
-<br>
+<br />
 
 <sl-alert variant="danger" open>
   <sl-icon slot="icon" name="exclamation-octagon"></sl-icon>
-    <strong>Your account has been deleted</strong><br>
-    We're very sorry to see you go!
+  <strong>Your account has been deleted</strong><br />
+  We're very sorry to see you go!
 </sl-alert>
 ```
 
@@ -77,7 +75,8 @@ const App = () => (
   <>
     <SlAlert variant="primary" open>
       <SlIcon slot="icon" name="info-circle" />
-      <strong>This is super informative</strong><br />
+      <strong>This is super informative</strong>
+      <br />
       You can tell by how pretty the alert is.
     </SlAlert>
 
@@ -85,7 +84,8 @@ const App = () => (
 
     <SlAlert variant="success" open>
       <SlIcon slot="icon" name="check2-circle" />
-      <strong>Your changes have been saved</strong><br />
+      <strong>Your changes have been saved</strong>
+      <br />
       You can safely exit the app now.
     </SlAlert>
 
@@ -93,7 +93,8 @@ const App = () => (
 
     <SlAlert variant="neutral" open>
       <SlIcon slot="icon" name="gear" />
-      <strong>Your settings have been updated</strong><br />
+      <strong>Your settings have been updated</strong>
+      <br />
       Settings will take affect on next login.
     </SlAlert>
 
@@ -101,7 +102,8 @@ const App = () => (
 
     <SlAlert variant="warning" open>
       <SlIcon slot="icon" name="exclamation-triangle" />
-      <strong>Your session has ended</strong><br />
+      <strong>Your session has ended</strong>
+      <br />
       Please login again to continue.
     </SlAlert>
 
@@ -109,8 +111,9 @@ const App = () => (
 
     <SlAlert variant="danger" open>
       <SlIcon slot="icon" name="exclamation-octagon" />
-        <strong>Your account has been deleted</strong><br />
-        We're very sorry to see you go!
+      <strong>Your account has been deleted</strong>
+      <br />
+      We're very sorry to see you go!
     </SlAlert>
   </>
 );
@@ -129,7 +132,7 @@ Add the `closable` attribute to show a close button that will hide the alert.
 <script>
   const alert = document.querySelector('.alert-closable');
   alert.addEventListener('sl-after-hide', () => {
-    setTimeout(() => alert.open = true, 2000);
+    setTimeout(() => (alert.open = true), 2000);
   });
 </script>
 ```
@@ -147,11 +150,7 @@ const App = () => {
   }
 
   return (
-    <SlAlert 
-      open={open}
-      closable
-      onSlAfterHide={handleHide}
-    >
+    <SlAlert open={open} closable onSlAfterHide={handleHide}>
       <SlIcon slot="icon" name="info-circle" />
       You can close this alert any time!
     </SlAlert>
@@ -164,9 +163,7 @@ const App = () => {
 Icons are optional. Simply omit the `icon` slot if you don't want them.
 
 ```html preview
-<sl-alert variant="primary" open>
-  Nothing fancy here, just a simple alert.
-</sl-alert>
+<sl-alert variant="primary" open> Nothing fancy here, just a simple alert. </sl-alert>
 ```
 
 ```jsx react
@@ -210,11 +207,7 @@ Set the `duration` attribute to automatically hide an alert after a period of ti
 
 ```jsx react
 import { useState } from 'react';
-import {
-  SlAlert,
-  SlButton,
-  SlIcon
-} from '@shoelace-style/shoelace/dist/react';
+import { SlAlert, SlButton, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .alert-duration sl-alert {
@@ -228,15 +221,11 @@ const App = () => {
   return (
     <>
       <div className="alert-duration">
-        <SlButton variant="primary" onClick={() => setOpen(true)}>Show Alert</SlButton>
+        <SlButton variant="primary" onClick={() => setOpen(true)}>
+          Show Alert
+        </SlButton>
 
-        <SlAlert 
-          variant="primary" 
-          duration="3000" 
-          open={open} 
-          closable 
-          onSlAfterHide={() => setOpen(false)}
-        >
+        <SlAlert variant="primary" duration="3000" open={open} closable onSlAfterHide={() => setOpen(false)}>
           <SlIcon slot="icon" name="info-circle" />
           This alert will automatically hide itself after three seconds, unless you interact with it.
         </SlAlert>
@@ -261,34 +250,34 @@ You should always use the `closable` attribute so users can dismiss the notifica
   <sl-button variant="neutral">Neutral</sl-button>
   <sl-button variant="warning">Warning</sl-button>
   <sl-button variant="danger">Danger</sl-button>
-  
+
   <sl-alert variant="primary" duration="3000" closable>
     <sl-icon slot="icon" name="info-circle"></sl-icon>
-    <strong>This is super informative</strong><br>
+    <strong>This is super informative</strong><br />
     You can tell by how pretty the alert is.
   </sl-alert>
 
   <sl-alert variant="success" duration="3000" closable>
     <sl-icon slot="icon" name="check2-circle"></sl-icon>
-    <strong>Your changes have been saved</strong><br>
+    <strong>Your changes have been saved</strong><br />
     You can safely exit the app now.
   </sl-alert>
 
   <sl-alert variant="neutral" duration="3000" closable>
     <sl-icon slot="icon" name="gear"></sl-icon>
-    <strong>Your settings have been updated</strong><br>
+    <strong>Your settings have been updated</strong><br />
     Settings will take affect on next login.
   </sl-alert>
 
   <sl-alert variant="warning" duration="3000" closable>
     <sl-icon slot="icon" name="exclamation-triangle"></sl-icon>
-    <strong>Your session has ended</strong><br>
+    <strong>Your session has ended</strong><br />
     Please login again to continue.
   </sl-alert>
 
   <sl-alert variant="danger" duration="3000" closable>
     <sl-icon slot="icon" name="exclamation-octagon"></sl-icon>
-    <strong>Your account has been deleted</strong><br>
+    <strong>Your account has been deleted</strong><br />
     We're very sorry to see you go!
   </sl-alert>
 </div>
@@ -307,11 +296,7 @@ You should always use the `closable` attribute so users can dismiss the notifica
 
 ```jsx react
 import { useRef } from 'react';
-import {
-  SlAlert,
-  SlButton,
-  SlIcon
-} from '@shoelace-style/shoelace/dist/react';
+import { SlAlert, SlButton, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 function showToast(alert) {
   alert.toast();
@@ -348,31 +333,36 @@ const App = () => {
 
       <SlAlert ref={primary} variant="primary" duration="3000" closable>
         <SlIcon slot="icon" name="info-circle" />
-        <strong>This is super informative</strong><br />
+        <strong>This is super informative</strong>
+        <br />
         You can tell by how pretty the alert is.
       </SlAlert>
 
       <SlAlert ref={success} variant="success" duration="3000" closable>
         <SlIcon slot="icon" name="check2-circle" />
-        <strong>Your changes have been saved</strong><br />
+        <strong>Your changes have been saved</strong>
+        <br />
         You can safely exit the app now.
       </SlAlert>
 
       <SlAlert ref={neutral} variant="neutral" duration="3000" closable>
         <SlIcon slot="icon" name="gear" />
-        <strong>Your settings have been updated</strong><br />
+        <strong>Your settings have been updated</strong>
+        <br />
         Settings will take affect on next login.
       </SlAlert>
 
       <SlAlert ref={warning} variant="warning" duration="3000" closable>
         <SlIcon slot="icon" name="exclamation-triangle" />
-        <strong>Your session has ended</strong><br />
+        <strong>Your session has ended</strong>
+        <br />
         Please login again to continue.
       </SlAlert>
 
       <SlAlert ref={danger} variant="danger" duration="3000" closable>
         <SlIcon slot="icon" name="exclamation-octagon" />
-        <strong>Your account has been deleted</strong><br />
+        <strong>Your account has been deleted</strong>
+        <br />
         We're very sorry to see you go!
       </SlAlert>
     </>
@@ -399,7 +389,7 @@ For convenience, you can create a utility that emits toast notifications with a
     const div = document.createElement('div');
     div.textContent = html;
     return div.innerHTML;
-  }  
+  }
 
   // Custom function to emit toast notifications
   function notify(message, variant = 'primary', icon = 'info-circle', duration = 3000) {

docs/components/animated-image.md

@@ -2,11 +2,9 @@
 
 [component-header:sl-animated-image]
 
-A component for displaying animated GIFs and WEBPs that play and pause on interaction.
-
 ```html preview
-<sl-animated-image 
-  src="https://shoelace.style/assets/images/walk.gif" 
+<sl-animated-image
+  src="https://shoelace.style/assets/images/walk.gif"
   alt="Animation of untied shoes walking on pavement"
 ></sl-animated-image>
 ```
@@ -16,7 +14,7 @@ import { SlAnimatedImage } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlAnimatedImage
-    src="https://shoelace.style/assets/images/walk.gif" 
+    src="https://shoelace.style/assets/images/walk.gif"
     alt="Animation of untied shoes walking on pavement"
   />
 );
@@ -31,8 +29,8 @@ const App = () => (
 Both GIF and WEBP images are supported.
 
 ```html preview
-<sl-animated-image 
-  src="https://shoelace.style/assets/images/tie.webp" 
+<sl-animated-image
+  src="https://shoelace.style/assets/images/tie.webp"
   alt="Animation of a shoe being tied"
 ></sl-animated-image>
 ```
@@ -41,10 +39,7 @@ Both GIF and WEBP images are supported.
 import { SlAnimatedImage } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlAnimatedImage
-    src="https://shoelace.style/assets/images/tie.webp" 
-    alt="Animation of a shoe being tied"
-  />
+  <SlAnimatedImage src="https://shoelace.style/assets/images/tie.webp" alt="Animation of a shoe being tied" />
 );
 ```
 
@@ -53,8 +48,8 @@ const App = () => (
 To set a custom size, apply a width and/or height to the host element.
 
 ```html preview
-<sl-animated-image 
-  src="https://shoelace.style/assets/images/walk.gif" 
+<sl-animated-image
+  src="https://shoelace.style/assets/images/walk.gif"
   alt="Animation of untied shoes walking on pavement"
   style="width: 150px; height: 200px;"
 >
@@ -66,7 +61,7 @@ import { SlAnimatedImage } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlAnimatedImage
-    src="https://shoelace.style/assets/images/walk.gif" 
+    src="https://shoelace.style/assets/images/walk.gif"
     alt="Animation of untied shoes walking on pavement"
     style={{ width: '150px', height: '200px' }}
   />
@@ -78,8 +73,8 @@ const App = () => (
 You can change the appearance and location of the control box by targeting the `control-box` part in your styles.
 
 ```html preview
-<sl-animated-image 
-  src="https://shoelace.style/assets/images/walk.gif" 
+<sl-animated-image
+  src="https://shoelace.style/assets/images/walk.gif"
   alt="Animation of untied shoes walking on pavement"
   class="animated-image-custom-control-box"
 ></sl-animated-image>
@@ -116,7 +111,7 @@ const App = () => (
   <>
     <SlAnimatedImage
       className="animated-image-custom-control-box"
-      src="https://shoelace.style/assets/images/walk.gif" 
+      src="https://shoelace.style/assets/images/walk.gif"
       alt="Animation of untied shoes walking on pavement"
     />
 

docs/components/animation.md

@@ -2,9 +2,7 @@
 
 [component-header:sl-animation]
 
-Animate elements declaratively with nearly 100 baked-in presets, or roll your own with custom keyframes. Powered by the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API).
-
-To animate an element, wrap it in `<sl-animation>` and set an animation `name`. The animation not start until you add the `play` attribute. Refer to the [properties table](#properties) for a list of all animation options.
+To animate an element, wrap it in `<sl-animation>` and set an animation `name`. The animation will not start until you add the `play` attribute. Refer to the [properties table](#properties) for a list of all animation options.
 
 ```html preview
 <div class="animation-overview">
@@ -41,13 +39,21 @@ const css = `
 const App = () => (
   <>
     <div class="animation-overview">
-      <SlAnimation name="bounce" duration={2000} play><div class="box" /></SlAnimation>
-      <SlAnimation name="jello" duration={2000} play><div class="box" /></SlAnimation>
-      <SlAnimation name="heartBeat" duration={2000} play><div class="box" /></SlAnimation>
-      <SlAnimation name="flip" duration={2000} play><div class="box" /></SlAnimation>
+      <SlAnimation name="bounce" duration={2000} play>
+        <div class="box" />
+      </SlAnimation>
+      <SlAnimation name="jello" duration={2000} play>
+        <div class="box" />
+      </SlAnimation>
+      <SlAnimation name="heartBeat" duration={2000} play>
+        <div class="box" />
+      </SlAnimation>
+      <SlAnimation name="flip" duration={2000} play>
+        <div class="box" />
+      </SlAnimation>
     </div>
 
-    <style>{css}</style> 
+    <style>{css}</style>
   </>
 );
 ```
@@ -85,24 +91,24 @@ This example demonstrates all of the baked-in animations and easings. Animations
   const easings = getEasingNames();
 
   animations.map(name => {
-    const menuItem = Object.assign(document.createElement('sl-menu-item'), {
+    const option = Object.assign(document.createElement('sl-option'), {
       textContent: name,
       value: name
     });
-    animationName.appendChild(menuItem);
-  });
-  
-  easings.map(name => {
-    const menuItem = Object.assign(document.createElement('sl-menu-item'), {
-      textContent: name,
-      value: name
-    });
-    easingName.appendChild(menuItem);
+    animationName.appendChild(option);
   });
 
-  animationName.addEventListener('sl-change', () => animation.name = animationName.value);
-  easingName.addEventListener('sl-change', () => animation.easing = easingName.value);
-  playbackRate.addEventListener('sl-input', () => animation.playbackRate = playbackRate.value);
+  easings.map(name => {
+    const option = Object.assign(document.createElement('sl-option'), {
+      textContent: name,
+      value: name
+    });
+    easingName.appendChild(option);
+  });
+
+  animationName.addEventListener('sl-change', () => (animation.name = animationName.value));
+  easingName.addEventListener('sl-change', () => (animation.easing = easingName.value));
+  playbackRate.addEventListener('sl-input', () => (animation.playbackRate = playbackRate.value));
 </script>
 
 <style>
@@ -156,7 +162,7 @@ Use an [Intersection Observer](https://developer.mozilla.org/en-US/docs/Web/API/
     width: 100px;
     height: 100px;
     background-color: var(--sl-color-primary-600);
-  }  
+  }
 </style>
 ```
 
@@ -182,16 +188,14 @@ const App = () => {
   const box = useRef(null);
 
   useEffect(() => {
-    const observer = new IntersectionObserver(
-      (entries) => {
-        if (entries[0].isIntersecting) {
-          animation.current.play = true;
-        } else {
-          animation.current.play = false;
-          animation.current.currentTime = 0;
-        }
+    const observer = new IntersectionObserver(entries => {
+      if (entries[0].isIntersecting) {
+        animation.current.play = true;
+      } else {
+        animation.current.play = false;
+        animation.current.currentTime = 0;
       }
-    );
+    });
 
     if (box.current) {
       observer.observe(box.current);
@@ -201,17 +205,12 @@ const App = () => {
   return (
     <>
       <div class="animation-scroll">
-        <SlAnimation
-          ref={animation}
-          name="jackInTheBox" 
-          duration={2000} 
-          iterations={1}
-        >
+        <SlAnimation ref={animation} name="jackInTheBox" duration={2000} iterations={1}>
           <div ref={box} class="box" />
         </SlAnimation>
       </div>
 
-      <style>{css}</style> 
+      <style>{css}</style>
     </>
   );
 };
@@ -271,9 +270,9 @@ const css = `
 const App = () => (
   <>
     <div class="animation-keyframes">
-      <SlAnimation 
-        easing="ease-in-out" 
-        duration={2000} 
+      <SlAnimation
+        easing="ease-in-out"
+        duration={2000}
         play
         keyframes={[
           {
@@ -296,7 +295,7 @@ const App = () => (
       </SlAnimation>
     </div>
 
-    <style>{css}</style> 
+    <style>{css}</style>
   </>
 );
 ```
@@ -332,13 +331,7 @@ const App = () => {
 
   return (
     <div class="animation-form">
-      <SlAnimation 
-        name="rubberBand" 
-        duration={1000} 
-        iterations={1} 
-        play={play}
-        onSlFinish={() => setPlay(false)}
-      >
+      <SlAnimation name="rubberBand" duration={1000} iterations={1} play={play} onSlFinish={() => setPlay(false)}>
         <SlButton variant="primary" onClick={() => setPlay(true)}>
           Click me
         </SlButton>

docs/components/avatar.md

@@ -2,32 +2,34 @@
 
 [component-header:sl-avatar]
 
-Avatars are used to represent a person or object.
-
-Like [images](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img), you should always provide `alt` text for avatars as alternate text for assistive devices.
+By default, a generic icon will be shown. You can personalize avatars by adding custom icons, initials, and images. You should always provide a `label` for assistive devices.
 
 ```html preview
-<sl-avatar alt="User avatar"></sl-avatar>
+<sl-avatar label="User avatar"></sl-avatar>
 ```
 
 ```jsx react
 import { SlAvatar } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlAvatar alt="User avatar" />
-);
+const App = () => <SlAvatar label="User avatar" />;
 ```
 
 ## Examples
 
 ### Images
 
-To use an image for the avatar, set the `image` and `alt` attributes. This will take priority and be shown over initials and icons.
+To use an image for the avatar, set the `image` and `label` attributes. This will take priority and be shown over initials and icons.
+Avatar images can be lazily loaded by setting the `loading` attribute to `lazy`.
 
 ```html preview
 <sl-avatar
   image="https://images.unsplash.com/photo-1529778873920-4da4926a72c2?ixlib=rb-1.2.1&auto=format&fit=crop&w=300&q=80"
-  alt="Avatar of a gray tabby kitten looking down"
+  label="Avatar of a gray tabby kitten looking down"
+></sl-avatar>
+<sl-avatar
+  image="https://images.unsplash.com/photo-1591871937573-74dbba515c4c?ixlib=rb-1.2.1&auto=format&fit=crop&w=300&q=80"
+  label="Avatar of a white and grey kitten on grey textile"
+  loading="lazy"
 ></sl-avatar>
 ```
 
@@ -37,7 +39,12 @@ import { SlAvatar } from '@shoelace-style/shoelace/dist/react';
 const App = () => (
   <SlAvatar
     image="https://images.unsplash.com/photo-1529778873920-4da4926a72c2?ixlib=rb-1.2.1&auto=format&fit=crop&w=300&q=80"
-    alt="Avatar of a gray tabby kitten looking down"
+    label="Avatar of a gray tabby kitten looking down"
+  />
+  <SlAvatar
+    image="https://images.unsplash.com/photo-1591871937573-74dbba515c4c?ixlib=rb-1.2.1&auto=format&fit=crop&w=300&q=80"
+    label="Avatar of a white and grey kitten on grey textile"
+    loading="lazy"
   />
 );
 ```
@@ -47,15 +54,13 @@ const App = () => (
 When you don't have an image to use, you can set the `initials` attribute to show something more personalized than an icon.
 
 ```html preview
-<sl-avatar initials="SL" alt="Avatar with initials: SL"></sl-avatar>
+<sl-avatar initials="SL" label="Avatar with initials: SL"></sl-avatar>
 ```
 
 ```jsx react
 import { SlAvatar } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlAvatar initials="SL" alt="Avatar with initials: SL" />
-);
+const App = () => <SlAvatar initials="SL" label="Avatar with initials: SL" />;
 ```
 
 ### Custom Icons
@@ -63,15 +68,15 @@ const App = () => (
 When no image or initials are set, an icon will be shown. The default avatar shows a generic "user" icon, but you can customize this with the `icon` slot.
 
 ```html preview
-<sl-avatar alt="Avatar with an image icon">
+<sl-avatar label="Avatar with an image icon">
   <sl-icon slot="icon" name="image"></sl-icon>
 </sl-avatar>
 
-<sl-avatar alt="Avatar with an archive icon">
+<sl-avatar label="Avatar with an archive icon">
   <sl-icon slot="icon" name="archive"></sl-icon>
 </sl-avatar>
 
-<sl-avatar alt="Avatar with a briefcase icon">
+<sl-avatar label="Avatar with a briefcase icon">
   <sl-icon slot="icon" name="briefcase"></sl-icon>
 </sl-avatar>
 ```
@@ -81,15 +86,15 @@ import { SlAvatar, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlAvatar alt="Avatar with an image icon">
+    <SlAvatar label="Avatar with an image icon">
       <SlIcon slot="icon" name="image" />
     </SlAvatar>
 
-    <SlAvatar alt="Avatar with an archive icon">
+    <SlAvatar label="Avatar with an archive icon">
       <SlIcon slot="icon" name="archive" />
     </SlAvatar>
 
-    <SlAvatar alt="Avatar with a briefcase icon">
+    <SlAvatar label="Avatar with a briefcase icon">
       <SlIcon slot="icon" name="briefcase" />
     </SlAvatar>
   </>
@@ -101,9 +106,9 @@ const App = () => (
 Avatars can be shaped using the `shape` attribute.
 
 ```html preview
-<sl-avatar shape="square" alt="Square avatar"></sl-avatar>
-<sl-avatar shape="rounded" alt="Rounded avatar"></sl-avatar>
-<sl-avatar shape="circle" alt="Circle avatar"></sl-avatar>
+<sl-avatar shape="square" label="Square avatar"></sl-avatar>
+<sl-avatar shape="rounded" label="Rounded avatar"></sl-avatar>
+<sl-avatar shape="circle" label="Circle avatar"></sl-avatar>
 ```
 
 ```jsx react
@@ -111,9 +116,9 @@ import { SlAvatar, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlAvatar shape="square" alt="Square avatar" />
-    <SlAvatar shape="rounded" alt="Rounded avatar" />
-    <SlAvatar shape="circle" alt="Circle avatar" />
+    <SlAvatar shape="square" label="Square avatar" />
+    <SlAvatar shape="rounded" label="Rounded avatar" />
+    <SlAvatar shape="circle" label="Circle avatar" />
   </>
 );
 ```
@@ -124,24 +129,24 @@ You can group avatars with a few lines of CSS.
 
 ```html preview
 <div class="avatar-group">
-  <sl-avatar 
+  <sl-avatar
     image="https://images.unsplash.com/photo-1490150028299-bf57d78394e0?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&q=80&crop=right"
-    alt="Avatar 1 of 4"
+    label="Avatar 1 of 4"
   ></sl-avatar>
 
-  <sl-avatar 
+  <sl-avatar
     image="https://images.unsplash.com/photo-1503454537195-1dcabb73ffb9?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=left&q=80"
-    alt="Avatar 2 of 4"
+    label="Avatar 2 of 4"
   ></sl-avatar>
 
-  <sl-avatar 
+  <sl-avatar
     image="https://images.unsplash.com/photo-1456439663599-95b042d50252?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=left&q=80"
-    alt="Avatar 3 of 4"
+    label="Avatar 3 of 4"
   ></sl-avatar>
 
-  <sl-avatar 
+  <sl-avatar
     image="https://images.unsplash.com/flagged/photo-1554078875-e37cb8b0e27d?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=top&q=80"
-    alt="Avatar 4 of 4"
+    label="Avatar 4 of 4"
   ></sl-avatar>
 </div>
 
@@ -172,28 +177,28 @@ const css = `
 const App = () => (
   <>
     <div className="avatar-group">
-      <SlAvatar 
-        image="https://images.unsplash.com/photo-1490150028299-bf57d78394e0?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&q=80&crop=right" 
-        alt="Avatar 1 of 4" 
+      <SlAvatar
+        image="https://images.unsplash.com/photo-1490150028299-bf57d78394e0?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&q=80&crop=right"
+        label="Avatar 1 of 4"
       />
 
-      <SlAvatar 
-        image="https://images.unsplash.com/photo-1503454537195-1dcabb73ffb9?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=left&q=80" 
-        alt="Avatar 2 of 4" 
+      <SlAvatar
+        image="https://images.unsplash.com/photo-1503454537195-1dcabb73ffb9?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=left&q=80"
+        label="Avatar 2 of 4"
       />
-      
-      <SlAvatar 
-        image="https://images.unsplash.com/photo-1456439663599-95b042d50252?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=left&q=80" 
-        alt="Avatar 3 of 4" 
+
+      <SlAvatar
+        image="https://images.unsplash.com/photo-1456439663599-95b042d50252?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=left&q=80"
+        label="Avatar 3 of 4"
       />
-      
-      <SlAvatar 
-        image="https://images.unsplash.com/flagged/photo-1554078875-e37cb8b0e27d?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=top&q=80" 
-        alt="Avatar 4 of 4" 
+
+      <SlAvatar
+        image="https://images.unsplash.com/flagged/photo-1554078875-e37cb8b0e27d?ixid=MXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%3D&ixlib=rb-1.2.1&auto=format&fit=crop&w=256&h=256&crop=top&q=80"
+        label="Avatar 4 of 4"
       />
     </div>
 
-    <style>{css}</style>    
+    <style>{css}</style>
   </>
 );
 ```

docs/components/badge.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-badge]
 
-Badges are used to draw attention and display statuses or counts.
-
 ```html preview
 <sl-badge>Badge</sl-badge>
 ```
@@ -11,9 +9,7 @@ Badges are used to draw attention and display statuses or counts.
 ```jsx react
 import { SlBadge } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlBadge>Badge</SlBadge>
-);
+const App = () => <SlBadge>Badge</SlBadge>;
 ```
 
 ## Examples
@@ -39,7 +35,7 @@ const App = () => (
     <SlBadge variant="success">Success</SlBadge>
     <SlBadge variant="neutral">Neutral</SlBadge>
     <SlBadge variant="warning">Warning</SlBadge>
-    <SlBadge variant="danger">Danger</SlBadge>  
+    <SlBadge variant="danger">Danger</SlBadge>
   </>
 );
 ```
@@ -61,11 +57,21 @@ import { SlBadge } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlBadge variant="primary" pill>Primary</SlBadge>
-    <SlBadge variant="success" pill>Success</SlBadge>
-    <SlBadge variant="neutral" pill>Neutral</SlBadge>
-    <SlBadge variant="warning" pill>Warning</SlBadge>
-    <SlBadge variant="danger" pill>Danger</SlBadge>  
+    <SlBadge variant="primary" pill>
+      Primary
+    </SlBadge>
+    <SlBadge variant="success" pill>
+      Success
+    </SlBadge>
+    <SlBadge variant="neutral" pill>
+      Neutral
+    </SlBadge>
+    <SlBadge variant="warning" pill>
+      Warning
+    </SlBadge>
+    <SlBadge variant="danger" pill>
+      Danger
+    </SlBadge>
   </>
 );
 ```
@@ -102,11 +108,21 @@ const css = `
 const App = () => (
   <>
     <div className="badge-pulse">
-      <SlBadge variant="primary" pill pulse>1</SlBadge>
-      <SlBadge variant="success" pill pulse>1</SlBadge>
-      <SlBadge variant="neutral" pill pulse>1</SlBadge>
-      <SlBadge variant="warning" pill pulse>1</SlBadge>
-      <SlBadge variant="danger" pill pulse>1</SlBadge>
+      <SlBadge variant="primary" pill pulse>
+        1
+      </SlBadge>
+      <SlBadge variant="success" pill pulse>
+        1
+      </SlBadge>
+      <SlBadge variant="neutral" pill pulse>
+        1
+      </SlBadge>
+      <SlBadge variant="warning" pill pulse>
+        1
+      </SlBadge>
+      <SlBadge variant="danger" pill pulse>
+        1
+      </SlBadge>
     </div>
 
     <style>{css}</style>
@@ -124,12 +140,12 @@ One of the most common use cases for badges is attaching them to buttons. To mak
   <sl-badge pill>30</sl-badge>
 </sl-button>
 
-<sl-button style="margin-left: 1rem;">
+<sl-button style="margin-inline-start: 1rem;">
   Warnings
   <sl-badge variant="warning" pill>8</sl-badge>
 </sl-button>
 
-<sl-button style="margin-left: 1rem;">
+<sl-button style="margin-inline-start: 1rem;">
   Errors
   <sl-badge variant="danger" pill>6</sl-badge>
 </sl-button>
@@ -145,14 +161,18 @@ const App = () => (
       <SlBadge pill>30</SlBadge>
     </SlButton>
 
-    <SlButton style={{ marginLeft: '1rem' }}>
+    <SlButton style={{ marginInlineStart: '1rem' }}>
       Warnings
-      <SlBadge variant="warning" pill>8</SlBadge>
+      <SlBadge variant="warning" pill>
+        8
+      </SlBadge>
     </SlButton>
 
-    <SlButton style={{ marginLeft: '1rem' }}>
+    <SlButton style={{ marginInlineStart: '1rem' }}>
       Errors
-      <SlBadge variant="danger" pill>6</SlBadge>
+      <SlBadge variant="danger" pill>
+        6
+      </SlBadge>
     </SlButton>
   </>
 );
@@ -163,7 +183,7 @@ const App = () => (
 When including badges in menu items, use the `suffix` slot to make sure they're aligned correctly.
 
 ```html preview
-<sl-menu style="max-width: 240px; border: solid 1px var(--sl-panel-border-color); border-radius: var(--sl-border-radius-medium);">
+<sl-menu style="max-width: 240px;">
   <sl-menu-label>Messages</sl-menu-label>
   <sl-menu-item>Comments <sl-badge slot="suffix" variant="neutral" pill>4</sl-badge></sl-menu-item>
   <sl-menu-item>Replies <sl-badge slot="suffix" variant="neutral" pill>12</sl-badge></sl-menu-item>
@@ -174,7 +194,7 @@ When including badges in menu items, use the `suffix` slot to make sure they're
 import { SlBadge, SlButton, SlMenu, SlMenuItem, SlMenuLabel } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlMenu 
+  <SlMenu
     style={{
       maxWidth: '240px',
       border: 'solid 1px var(--sl-panel-border-color)',
@@ -182,8 +202,18 @@ const App = () => (
     }}
   >
     <SlMenuLabel>Messages</SlMenuLabel>
-    <SlMenuItem>Comments <SlBadge slot="suffix" variant="neutral" pill>4</SlBadge></SlMenuItem>
-    <SlMenuItem>Replies <SlBadge slot="suffix" variant="neutral" pill>12</SlBadge></SlMenuItem>
+    <SlMenuItem>
+      Comments
+      <SlBadge slot="suffix" variant="neutral" pill>
+        4
+      </SlBadge>
+    </SlMenuItem>
+    <SlMenuItem>
+      Replies
+      <SlBadge slot="suffix" variant="neutral" pill>
+        12
+      </SlBadge>
+    </SlMenuItem>
   </SlMenu>
 );
 ```

docs/components/breadcrumb-item.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-breadcrumb-item]
 
-Breadcrumb Items are used inside [breadcrumbs](/components/breadcrumb) to represent different links.
-
 ```html preview
 <sl-breadcrumb>
   <sl-breadcrumb-item>

docs/components/breadcrumb.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-breadcrumb]
 
-Breadcrumbs provide a group of links so users can easily navigate a website's hierarchy.
-
 Breadcrumbs are usually placed before a page's main content with the current page shown last to indicate the user's position in the navigation.
 
 ```html preview
@@ -38,21 +36,13 @@ For websites, you'll probably want to use links instead. You can make any breadc
 
 ```html preview
 <sl-breadcrumb>
-  <sl-breadcrumb-item href="https://example.com/home">
-    Homepage
-  </sl-breadcrumb-item>
+  <sl-breadcrumb-item href="https://example.com/home">Homepage</sl-breadcrumb-item>
 
-  <sl-breadcrumb-item href="https://example.com/home/services">
-    Our Services
-  </sl-breadcrumb-item>
+  <sl-breadcrumb-item href="https://example.com/home/services">Our Services</sl-breadcrumb-item>
 
-  <sl-breadcrumb-item href="https://example.com/home/services/digital">
-    Digital Media
-  </sl-breadcrumb-item>
+  <sl-breadcrumb-item href="https://example.com/home/services/digital">Digital Media</sl-breadcrumb-item>
 
-  <sl-breadcrumb-item href="https://example.com/home/services/digital/web-design">
-    Web Design
-  </sl-breadcrumb-item>
+  <sl-breadcrumb-item href="https://example.com/home/services/digital/web-design">Web Design</sl-breadcrumb-item>
 </sl-breadcrumb>
 ```
 
@@ -61,21 +51,13 @@ import { SlBreadcrumb, SlBreadcrumbItem } from '@shoelace-style/shoelace/dist/re
 
 const App = () => (
   <SlBreadcrumb>
-    <SlBreadcrumbItem href="https://example.com/home">
-      Homepage
-    </SlBreadcrumbItem>
+    <SlBreadcrumbItem href="https://example.com/home">Homepage</SlBreadcrumbItem>
 
-    <SlBreadcrumbItem href="https://example.com/home/services">
-      Our Services
-    </SlBreadcrumbItem>
+    <SlBreadcrumbItem href="https://example.com/home/services">Our Services</SlBreadcrumbItem>
 
-    <SlBreadcrumbItem href="https://example.com/home/services/digital">
-      Digital Media
-    </SlBreadcrumbItem>
+    <SlBreadcrumbItem href="https://example.com/home/services/digital">Digital Media</SlBreadcrumbItem>
 
-    <SlBreadcrumbItem href="https://example.com/home/services/digital/web-design">
-      Web Design
-    </SlBreadcrumbItem>
+    <SlBreadcrumbItem href="https://example.com/home/services/digital/web-design">Web Design</SlBreadcrumbItem>
   </SlBreadcrumb>
 );
 ```
@@ -89,25 +71,25 @@ Use the `separator` slot to change the separator that goes between breadcrumb it
   <sl-icon name="dot" slot="separator"></sl-icon>
   <sl-breadcrumb-item>First</sl-breadcrumb-item>
   <sl-breadcrumb-item>Second</sl-breadcrumb-item>
-  <sl-breadcrumb-item>Third</sl-breadcrumb-item> 
+  <sl-breadcrumb-item>Third</sl-breadcrumb-item>
 </sl-breadcrumb>
 
-<br>
+<br />
 
 <sl-breadcrumb>
   <sl-icon name="arrow-right" slot="separator"></sl-icon>
   <sl-breadcrumb-item>First</sl-breadcrumb-item>
   <sl-breadcrumb-item>Second</sl-breadcrumb-item>
-  <sl-breadcrumb-item>Third</sl-breadcrumb-item> 
+  <sl-breadcrumb-item>Third</sl-breadcrumb-item>
 </sl-breadcrumb>
 
-<br>
+<br />
 
 <sl-breadcrumb>
   <span slot="separator">/</span>
   <sl-breadcrumb-item>First</sl-breadcrumb-item>
   <sl-breadcrumb-item>Second</sl-breadcrumb-item>
-  <sl-breadcrumb-item>Third</sl-breadcrumb-item> 
+  <sl-breadcrumb-item>Third</sl-breadcrumb-item>
 </sl-breadcrumb>
 ```
 
@@ -121,7 +103,7 @@ const App = () => (
       <sl-icon name="dot" slot="separator" />
       <SlBreadcrumbItem>First</SlBreadcrumbItem>
       <SlBreadcrumbItem>Second</SlBreadcrumbItem>
-      <SlBreadcrumbItem>Third</SlBreadcrumbItem> 
+      <SlBreadcrumbItem>Third</SlBreadcrumbItem>
     </SlBreadcrumb>
 
     <br />
@@ -130,7 +112,7 @@ const App = () => (
       <sl-icon name="arrow-right" slot="separator" />
       <SlBreadcrumbItem>First</SlBreadcrumbItem>
       <SlBreadcrumbItem>Second</SlBreadcrumbItem>
-      <SlBreadcrumbItem>Third</SlBreadcrumbItem> 
+      <SlBreadcrumbItem>Third</SlBreadcrumbItem>
     </SlBreadcrumb>
 
     <br />
@@ -139,7 +121,7 @@ const App = () => (
       <span slot="separator">/</span>
       <SlBreadcrumbItem>First</SlBreadcrumbItem>
       <SlBreadcrumbItem>Second</SlBreadcrumbItem>
-      <SlBreadcrumbItem>Third</SlBreadcrumbItem> 
+      <SlBreadcrumbItem>Third</SlBreadcrumbItem>
     </SlBreadcrumb>
   </>
 );
@@ -221,19 +203,19 @@ Dropdown menus can be placed in a prefix or suffix slot to provide additional op
         <sl-icon label="More options" name="three-dots"></sl-icon>
       </sl-button>
       <sl-menu>
-        <sl-menu-item checked>Web Design</sl-menu-item>
-        <sl-menu-item>Web Development</sl-menu-item>
-        <sl-menu-item>Marketing</sl-menu-item>
+        <sl-menu-item type="checkbox" checked>Web Design</sl-menu-item>
+        <sl-menu-item type="checkbox">Web Development</sl-menu-item>
+        <sl-menu-item type="checkbox">Marketing</sl-menu-item>
       </sl-menu>
-    </sl-dropdown>    
+    </sl-dropdown>
   </sl-breadcrumb-item>
 </sl-breadcrumb>
 ```
 
 ```jsx react
-import { 
-  SlBreadcrumb, 
-  SlBreadcrumbItem, 
+import {
+  SlBreadcrumb,
+  SlBreadcrumbItem,
   SlButton,
   SlDropdown,
   SlIcon,
@@ -253,11 +235,13 @@ const App = () => (
           <SlIcon label="More options" name="three-dots"></SlIcon>
         </SlButton>
         <SlMenu>
-          <SlMenuItem checked>Web Design</SlMenuItem>
-          <SlMenuItem>Web Development</SlMenuItem>
-          <SlMenuItem>Marketing</SlMenuItem>
+          <SlMenuItem type="checkbox" checked>
+            Web Design
+          </SlMenuItem>
+          <SlMenuItem type="checkbox">Web Development</SlMenuItem>
+          <SlMenuItem type="checkbox">Marketing</SlMenuItem>
         </SlMenu>
-      </SlDropdown>    
+      </SlDropdown>
     </SlBreadcrumbItem>
   </SlBreadcrumb>
 );

docs/components/button-group.md

@@ -2,10 +2,8 @@
 
 [component-header:sl-button-group]
 
-Button groups can be used to group related buttons into sections.
-
 ```html preview
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-button>Left</sl-button>
   <sl-button>Center</sl-button>
   <sl-button>Right</sl-button>
@@ -16,7 +14,7 @@ Button groups can be used to group related buttons into sections.
 import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlButtonGroup>
+  <SlButtonGroup label="Alignment">
     <SlButton>Left</SlButton>
     <SlButton>Center</SlButton>
     <SlButton>Right</SlButton>
@@ -31,23 +29,23 @@ const App = () => (
 All button sizes are supported, but avoid mixing sizes within the same button group.
 
 ```html preview
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-button size="small">Left</sl-button>
   <sl-button size="small">Center</sl-button>
   <sl-button size="small">Right</sl-button>
 </sl-button-group>
 
-<br><br>
+<br /><br />
 
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-button size="medium">Left</sl-button>
   <sl-button size="medium">Center</sl-button>
   <sl-button size="medium">Right</sl-button>
 </sl-button-group>
 
-<br><br>
+<br /><br />
 
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-button size="large">Left</sl-button>
   <sl-button size="large">Center</sl-button>
   <sl-button size="large">Right</sl-button>
@@ -59,23 +57,25 @@ import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlButtonGroup>
+    <SlButtonGroup label="Alignment">
       <SlButton size="small">Left</SlButton>
       <SlButton size="small">Center</SlButton>
       <SlButton size="small">Right</SlButton>
     </SlButtonGroup>
 
-    <br /><br />
+    <br />
+    <br />
 
-    <SlButtonGroup>
+    <SlButtonGroup label="Alignment">
       <SlButton size="medium">Left</SlButton>
       <SlButton size="medium">Center</SlButton>
       <SlButton size="medium">Right</SlButton>
     </SlButtonGroup>
 
-    <br /><br />
+    <br />
+    <br />
 
-    <SlButtonGroup>
+    <SlButtonGroup label="Alignment">
       <SlButton size="large">Left</SlButton>
       <SlButton size="large">Center</SlButton>
       <SlButton size="large">Right</SlButton>
@@ -86,42 +86,42 @@ const App = () => (
 
 ### Theme Buttons
 
-Theme buttons are supported through the button's `type` attribute.
+Theme buttons are supported through the button's `variant` attribute.
 
 ```html preview
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-button variant="primary">Left</sl-button>
   <sl-button variant="primary">Center</sl-button>
   <sl-button variant="primary">Right</sl-button>
 </sl-button-group>
 
-<br><br>
+<br /><br />
 
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-button variant="success">Left</sl-button>
   <sl-button variant="success">Center</sl-button>
   <sl-button variant="success">Right</sl-button>
 </sl-button-group>
 
-<br><br>
+<br /><br />
 
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-button variant="neutral">Left</sl-button>
   <sl-button variant="neutral">Center</sl-button>
   <sl-button variant="neutral">Right</sl-button>
 </sl-button-group>
 
-<br><br>
+<br /><br />
 
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-button variant="warning">Left</sl-button>
   <sl-button variant="warning">Center</sl-button>
   <sl-button variant="warning">Right</sl-button>
 </sl-button-group>
 
-<br><br>
+<br /><br />
 
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-button variant="danger">Left</sl-button>
   <sl-button variant="danger">Center</sl-button>
   <sl-button variant="danger">Right</sl-button>
@@ -133,39 +133,43 @@ import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlButtonGroup>
+    <SlButtonGroup label="Alignment">
       <SlButton variant="primary">Left</SlButton>
       <SlButton variant="primary">Center</SlButton>
       <SlButton variant="primary">Right</SlButton>
     </SlButtonGroup>
 
-    <br /><br />
+    <br />
+    <br />
 
-    <SlButtonGroup>
+    <SlButtonGroup label="Alignment">
       <SlButton variant="success">Left</SlButton>
       <SlButton variant="success">Center</SlButton>
       <SlButton variant="success">Right</SlButton>
     </SlButtonGroup>
 
-    <br /><br />
+    <br />
+    <br />
 
-    <SlButtonGroup>
+    <SlButtonGroup label="Alignment">
       <SlButton variant="neutral">Left</SlButton>
       <SlButton variant="neutral">Center</SlButton>
       <SlButton variant="neutral">Right</SlButton>
     </SlButtonGroup>
 
-    <br /><br />
+    <br />
+    <br />
 
-    <SlButtonGroup>
+    <SlButtonGroup label="Alignment">
       <SlButton variant="warning">Left</SlButton>
       <SlButton variant="warning">Center</SlButton>
       <SlButton variant="warning">Right</SlButton>
     </SlButtonGroup>
 
-    <br /><br />
+    <br />
+    <br />
 
-    <SlButtonGroup>
+    <SlButtonGroup label="Alignment">
       <SlButton variant="danger">Left</SlButton>
       <SlButton variant="danger">Center</SlButton>
       <SlButton variant="danger">Right</SlButton>
@@ -179,23 +183,23 @@ const App = () => (
 Pill buttons are supported through the button's `pill` attribute.
 
 ```html preview
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-button size="small" pill>Left</sl-button>
   <sl-button size="small" pill>Center</sl-button>
   <sl-button size="small" pill>Right</sl-button>
 </sl-button-group>
 
-<br><br>
+<br /><br />
 
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-button size="medium" pill>Left</sl-button>
   <sl-button size="medium" pill>Center</sl-button>
   <sl-button size="medium" pill>Right</sl-button>
 </sl-button-group>
 
-<br><br>
+<br /><br />
 
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-button size="large" pill>Left</sl-button>
   <sl-button size="large" pill>Center</sl-button>
   <sl-button size="large" pill>Right</sl-button>
@@ -207,26 +211,46 @@ import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlButtonGroup>
-      <SlButton size="small" pill>Left</SlButton>
-      <SlButton size="small" pill>Center</SlButton>
-      <SlButton size="small" pill>Right</SlButton>
+    <SlButtonGroup label="Alignment">
+      <SlButton size="small" pill>
+        Left
+      </SlButton>
+      <SlButton size="small" pill>
+        Center
+      </SlButton>
+      <SlButton size="small" pill>
+        Right
+      </SlButton>
     </SlButtonGroup>
 
-    <br /><br />
+    <br />
+    <br />
 
-    <SlButtonGroup>
-      <SlButton size="medium" pill>Left</SlButton>
-      <SlButton size="medium" pill>Center</SlButton>
-      <SlButton size="medium" pill>Right</SlButton>
+    <SlButtonGroup label="Alignment">
+      <SlButton size="medium" pill>
+        Left
+      </SlButton>
+      <SlButton size="medium" pill>
+        Center
+      </SlButton>
+      <SlButton size="medium" pill>
+        Right
+      </SlButton>
     </SlButtonGroup>
 
-    <br /><br />
+    <br />
+    <br />
 
-    <SlButtonGroup>
-      <SlButton size="large" pill>Left</SlButton>
-      <SlButton size="large" pill>Center</SlButton>
-      <SlButton size="large" pill>Right</SlButton>
+    <SlButtonGroup label="Alignment">
+      <SlButton size="large" pill>
+        Left
+      </SlButton>
+      <SlButton size="large" pill>
+        Center
+      </SlButton>
+      <SlButton size="large" pill>
+        Right
+      </SlButton>
     </SlButtonGroup>
   </>
 );
@@ -237,7 +261,7 @@ const App = () => (
 Dropdowns can be placed inside button groups as long as the trigger is an `<sl-button>` element.
 
 ```html preview
-<sl-button-group> 
+<sl-button-group label="Example Button Group">
   <sl-button>Button</sl-button>
   <sl-button>Button</sl-button>
   <sl-dropdown>
@@ -252,20 +276,16 @@ Dropdowns can be placed inside button groups as long as the trigger is an `<sl-b
 ```
 
 ```jsx react
-import { 
-  SlButton, 
-  SlButtonGroup,
-  SlDropdown,
-  SlMenu,
-  SlMenuItem,
-} from '@shoelace-style/shoelace/dist/react';
+import { SlButton, SlButtonGroup, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlButtonGroup> 
+  <SlButtonGroup label="Example Button Group">
     <SlButton>Button</SlButton>
     <SlButton>Button</SlButton>
     <SlDropdown>
-      <SlButton slot="trigger" caret>Dropdown</SlButton>
+      <SlButton slot="trigger" caret>
+        Dropdown
+      </SlButton>
       <SlMenu>
         <SlMenuItem>Item 1</SlMenuItem>
         <SlMenuItem>Item 2</SlMenuItem>
@@ -278,13 +298,15 @@ const App = () => (
 
 ### Split Buttons
 
-Create a split button using a button and a dropdown.
+Create a split button using a button and a dropdown. Use a [visually hidden](/components/visually-hidden) label to ensure the dropdown is accessible to users with assistive devices.
 
 ```html preview
-<sl-button-group> 
+<sl-button-group label="Example Button Group">
   <sl-button variant="primary">Save</sl-button>
   <sl-dropdown placement="bottom-end">
-    <sl-button slot="trigger" variant="primary" caret></sl-button>
+    <sl-button slot="trigger" variant="primary" caret>
+      <sl-visually-hidden>More options</sl-visually-hidden>
+    </sl-button>
     <sl-menu>
       <sl-menu-item>Save</sl-menu-item>
       <sl-menu-item>Save as&hellip;</sl-menu-item>
@@ -295,16 +317,10 @@ Create a split button using a button and a dropdown.
 ```
 
 ```jsx react
-import { 
-  SlButton, 
-  SlButtonGroup,
-  SlDropdown,
-  SlMenu,
-  SlMenuItem,
-} from '@shoelace-style/shoelace/dist/react';
+import { SlButton, SlButtonGroup, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlButtonGroup> 
+  <SlButtonGroup label="Example Button Group">
     <SlButton variant="primary">Save</SlButton>
     <SlDropdown placement="bottom-end">
       <SlButton slot="trigger" variant="primary" caret></SlButton>
@@ -323,7 +339,7 @@ const App = () => (
 Buttons can be wrapped in tooltips to provide more detail when the user interacts with them.
 
 ```html preview
-<sl-button-group>
+<sl-button-group label="Alignment">
   <sl-tooltip content="I'm on the left">
     <sl-button>Left</sl-button>
   </sl-tooltip>
@@ -339,15 +355,11 @@ Buttons can be wrapped in tooltips to provide more detail when the user interact
 ```
 
 ```jsx react
-import { 
-  SlButton, 
-  SlButtonGroup,
-  SlTooltip
-} from '@shoelace-style/shoelace/dist/react';
+import { SlButton, SlButtonGroup, SlTooltip } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlButtonGroup>
+    <SlButtonGroup label="Alignment">
       <SlTooltip content="I'm on the left">
         <SlButton>Left</SlButton>
       </SlTooltip>
@@ -372,34 +384,34 @@ Create interactive toolbars with button groups.
 <div class="button-group-toolbar">
   <sl-button-group label="History">
     <sl-tooltip content="Undo">
-      <sl-button><sl-icon name="arrow-counterclockwise"></sl-icon></sl-button>
+      <sl-button><sl-icon name="arrow-counterclockwise" label="Undo"></sl-icon></sl-button>
     </sl-tooltip>
     <sl-tooltip content="Redo">
-      <sl-button><sl-icon name="arrow-clockwise"></sl-icon></sl-button>
+      <sl-button><sl-icon name="arrow-clockwise" label="Redo"></sl-icon></sl-button>
     </sl-tooltip>
   </sl-button-group>
 
   <sl-button-group label="Formatting">
     <sl-tooltip content="Bold">
-      <sl-button><sl-icon name="type-bold"></sl-icon></sl-button>
+      <sl-button><sl-icon name="type-bold" label="Bold"></sl-icon></sl-button>
     </sl-tooltip>
     <sl-tooltip content="Italic">
-      <sl-button><sl-icon name="type-italic"></sl-icon></sl-button>
+      <sl-button><sl-icon name="type-italic" label="Italic"></sl-icon></sl-button>
     </sl-tooltip>
     <sl-tooltip content="Underline">
-      <sl-button><sl-icon name="type-underline"></sl-icon></sl-button>
+      <sl-button><sl-icon name="type-underline" label="Underline"></sl-icon></sl-button>
     </sl-tooltip>
   </sl-button-group>
 
   <sl-button-group label="Alignment">
     <sl-tooltip content="Align Left">
-      <sl-button><sl-icon name="justify-left"></sl-icon></sl-button>
+      <sl-button><sl-icon name="justify-left" label="Align Left"></sl-icon></sl-button>
     </sl-tooltip>
     <sl-tooltip content="Align Center">
-      <sl-button><sl-icon name="justify"></sl-icon></sl-button>
+      <sl-button><sl-icon name="justify" label="Align Center"></sl-icon></sl-button>
     </sl-tooltip>
     <sl-tooltip content="Align Right">
-      <sl-button><sl-icon name="justify-right"></sl-icon></sl-button>
+      <sl-button><sl-icon name="justify-right" label="Align Right"></sl-icon></sl-button>
     </sl-tooltip>
   </sl-button-group>
 </div>
@@ -412,12 +424,7 @@ Create interactive toolbars with button groups.
 ```
 
 ```jsx react
-import { 
-  SlButton, 
-  SlButtonGroup,
-  SlIcon,
-  SlTooltip
-} from '@shoelace-style/shoelace/dist/react';
+import { SlButton, SlButtonGroup, SlIcon, SlTooltip } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .button-group-toolbar sl-button-group:not(:last-of-type) {
@@ -430,34 +437,50 @@ const App = () => (
     <div className="button-group-toolbar">
       <SlButtonGroup label="History">
         <SlTooltip content="Undo">
-          <SlButton><SlIcon name="arrow-counterclockwise"></SlIcon></SlButton>
+          <SlButton>
+            <SlIcon name="arrow-counterclockwise"></SlIcon>
+          </SlButton>
         </SlTooltip>
         <SlTooltip content="Redo">
-          <SlButton><SlIcon name="arrow-clockwise"></SlIcon></SlButton>
+          <SlButton>
+            <SlIcon name="arrow-clockwise"></SlIcon>
+          </SlButton>
         </SlTooltip>
       </SlButtonGroup>
 
       <SlButtonGroup label="Formatting">
         <SlTooltip content="Bold">
-          <SlButton><SlIcon name="type-bold"></SlIcon></SlButton>
+          <SlButton>
+            <SlIcon name="type-bold"></SlIcon>
+          </SlButton>
         </SlTooltip>
         <SlTooltip content="Italic">
-          <SlButton><SlIcon name="type-italic"></SlIcon></SlButton>
+          <SlButton>
+            <SlIcon name="type-italic"></SlIcon>
+          </SlButton>
         </SlTooltip>
         <SlTooltip content="Underline">
-          <SlButton><SlIcon name="type-underline"></SlIcon></SlButton>
+          <SlButton>
+            <SlIcon name="type-underline"></SlIcon>
+          </SlButton>
         </SlTooltip>
       </SlButtonGroup>
 
       <SlButtonGroup label="Alignment">
         <SlTooltip content="Align Left">
-          <SlButton><SlIcon name="justify-left"></SlIcon></SlButton>
+          <SlButton>
+            <SlIcon name="justify-left"></SlIcon>
+          </SlButton>
         </SlTooltip>
         <SlTooltip content="Align Center">
-          <SlButton><SlIcon name="justify"></SlIcon></SlButton>
+          <SlButton>
+            <SlIcon name="justify"></SlIcon>
+          </SlButton>
         </SlTooltip>
         <SlTooltip content="Align Right">
-          <SlButton><SlIcon name="justify-right"></SlIcon></SlButton>
+          <SlButton>
+            <SlIcon name="justify-right"></SlIcon>
+          </SlButton>
         </SlTooltip>
       </SlButtonGroup>
     </div>

docs/components/button.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-button]
 
-Buttons represent actions that are available to the user.
-
 ```html preview
 <sl-button>Button</sl-button>
 ```
@@ -11,9 +9,7 @@ Buttons represent actions that are available to the user.
 ```jsx react
 import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlButton>Button</SlButton>
-);
+const App = () => <SlButton>Button</SlButton>;
 ```
 
 ## Examples
@@ -41,7 +37,7 @@ const App = () => (
     <SlButton variant="success">Success</SlButton>
     <SlButton variant="neutral">Neutral</SlButton>
     <SlButton variant="warning">Warning</SlButton>
-    <SlButton variant="danger">Danger</SlButton>  
+    <SlButton variant="danger">Danger</SlButton>
   </>
 );
 ```
@@ -86,12 +82,24 @@ import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlButton variant="default" outline>Default</SlButton>
-    <SlButton variant="primary" outline>Primary</SlButton>
-    <SlButton variant="success" outline>Success</SlButton>
-    <SlButton variant="neutral" outline>Neutral</SlButton>
-    <SlButton variant="warning" outline>Warning</SlButton>
-    <SlButton variant="danger" outline>Danger</SlButton>
+    <SlButton variant="default" outline>
+      Default
+    </SlButton>
+    <SlButton variant="primary" outline>
+      Primary
+    </SlButton>
+    <SlButton variant="success" outline>
+      Success
+    </SlButton>
+    <SlButton variant="neutral" outline>
+      Neutral
+    </SlButton>
+    <SlButton variant="warning" outline>
+      Warning
+    </SlButton>
+    <SlButton variant="danger" outline>
+      Danger
+    </SlButton>
   </>
 );
 ```
@@ -111,21 +119,35 @@ import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlButton size="small" pill>Small</SlButton>
-    <SlButton size="medium" pill>Medium</SlButton>
-    <SlButton size="large" pill>Large</SlButton>
+    <SlButton size="small" pill>
+      Small
+    </SlButton>
+    <SlButton size="medium" pill>
+      Medium
+    </SlButton>
+    <SlButton size="large" pill>
+      Large
+    </SlButton>
   </>
 );
 ```
 
 ### Circle Buttons
 
-Use the `circle` attribute to create circular icon buttons.
+Use the `circle` attribute to create circular icon buttons. When this attribute is set, the button expects a single `<sl-icon>` in the default slot.
 
 ```html preview
-<sl-button variant="default" size="small" circle><sl-icon name="gear"></sl-icon></sl-button>
-<sl-button variant="default" size="medium" circle><sl-icon name="gear"></sl-icon></sl-button>
-<sl-button variant="default" size="large" circle><sl-icon name="gear"></sl-icon></sl-button>
+<sl-button variant="default" size="small" circle>
+  <sl-icon name="gear" label="Settings"></sl-icon>
+</sl-button>
+
+<sl-button variant="default" size="medium" circle>
+  <sl-icon name="gear" label="Settings"></sl-icon>
+</sl-button>
+
+<sl-button variant="default" size="large" circle>
+  <sl-icon name="gear" label="Settings"></sl-icon>
+</sl-button>
 ```
 
 ```jsx react
@@ -133,9 +155,15 @@ import { SlButton, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlButton variant="default" size="small" circle><SlIcon name="gear" /></SlButton>
-    <SlButton variant="default" size="medium" circle><SlIcon name="gear" /></SlButton>
-    <SlButton variant="default" size="large" circle><SlIcon name="gear" /></SlButton>
+    <SlButton variant="default" size="small" circle>
+      <SlIcon name="gear" />
+    </SlButton>
+    <SlButton variant="default" size="medium" circle>
+      <SlIcon name="gear" />
+    </SlButton>
+    <SlButton variant="default" size="large" circle>
+      <SlIcon name="gear" />
+    </SlButton>
   </>
 );
 ```
@@ -155,9 +183,15 @@ import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlButton variant="text" size="small">Text</SlButton>
-    <SlButton variant="text" size="medium">Text</SlButton>
-    <SlButton variant="text" size="large">Text</SlButton>
+    <SlButton variant="text" size="small">
+      Text
+    </SlButton>
+    <SlButton variant="text" size="medium">
+      Text
+    </SlButton>
+    <SlButton variant="text" size="large">
+      Text
+    </SlButton>
   </>
 );
 ```
@@ -179,9 +213,15 @@ import { SlButton } from '@shoelace-style/shoelace/dist/react';
 const App = () => (
   <>
     <SlButton href="https://example.com/">Link</SlButton>
-    <SlButton href="https://example.com/" target="_blank">New Window</SlButton>
-    <SlButton href="/assets/images/wordmark.svg" download="shoelace.svg">Download</SlButton>
-    <SlButton href="https://example.com/" disabled>Disabled</SlButton>
+    <SlButton href="https://example.com/" target="_blank">
+      New Window
+    </SlButton>
+    <SlButton href="/assets/images/wordmark.svg" download="shoelace.svg">
+      Download
+    </SlButton>
+    <SlButton href="https://example.com/" disabled>
+      Disabled
+    </SlButton>
   </>
 );
 ```
@@ -203,9 +243,15 @@ import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlButton variant="default" size="small" style={{ width: '100%', marginBottom: '1rem' }}>Small</SlButton>
-    <SlButton variant="default" size="medium" style={{ width: '100%', marginBottom: '1rem' }}>Medium</SlButton>
-    <SlButton variant="default" size="large" style={{ width: '100%' }}>Large</SlButton>
+    <SlButton variant="default" size="small" style={{ width: '100%', marginBottom: '1rem' }}>
+      Small
+    </SlButton>
+    <SlButton variant="default" size="medium" style={{ width: '100%', marginBottom: '1rem' }}>
+      Medium
+    </SlButton>
+    <SlButton variant="default" size="large" style={{ width: '100%' }}>
+      Large
+    </SlButton>
   </>
 );
 ```
@@ -231,7 +277,7 @@ Use the `prefix` and `suffix` slots to add icons.
   Open
 </sl-button>
 
-<br><br>
+<br /><br />
 
 <sl-button variant="default">
   <sl-icon slot="prefix" name="gear"></sl-icon>
@@ -249,7 +295,7 @@ Use the `prefix` and `suffix` slots to add icons.
   Open
 </sl-button>
 
-<br><br>
+<br /><br />
 
 <sl-button variant="default" size="large">
   <sl-icon slot="prefix" name="gear"></sl-icon>
@@ -289,7 +335,8 @@ const App = () => (
       Open
     </SlButton>
 
-    <br /><br/ >
+    <br />
+    <br />
 
     <SlButton variant="default">
       <SlIcon slot="prefix" name="gear"></SlIcon>
@@ -307,7 +354,8 @@ const App = () => (
       Open
     </SlButton>
 
-    <br /><br />
+    <br />
+    <br />
 
     <SlButton variant="default" size="large">
       <SlIcon slot="prefix" name="gear"></SlIcon>
@@ -343,9 +391,15 @@ import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlButton size="small" caret>Small</SlButton>
-    <SlButton size="medium" caret>Medium</SlButton>
-    <SlButton size="large" caret>Large</SlButton>
+    <SlButton size="small" caret>
+      Small
+    </SlButton>
+    <SlButton size="medium" caret>
+      Medium
+    </SlButton>
+    <SlButton size="large" caret>
+      Large
+    </SlButton>
   </>
 );
 ```
@@ -368,12 +422,24 @@ import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlButton variant="default" loading>Default</SlButton>
-    <SlButton variant="primary" loading>Primary</SlButton>
-    <SlButton variant="success" loading>Success</SlButton>
-    <SlButton variant="neutral" loading>Neutral</SlButton>
-    <SlButton variant="warning" loading>Warning</SlButton>
-    <SlButton variant="danger" loading>Danger</SlButton>
+    <SlButton variant="default" loading>
+      Default
+    </SlButton>
+    <SlButton variant="primary" loading>
+      Primary
+    </SlButton>
+    <SlButton variant="success" loading>
+      Success
+    </SlButton>
+    <SlButton variant="neutral" loading>
+      Neutral
+    </SlButton>
+    <SlButton variant="warning" loading>
+      Warning
+    </SlButton>
+    <SlButton variant="danger" loading>
+      Danger
+    </SlButton>
   </>
 );
 ```
@@ -396,12 +462,29 @@ import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlButton variant="default" disabled>Default</SlButton>
-    <SlButton variant="primary" disabled>Primary</SlButton>
-    <SlButton variant="success" disabled>Success</SlButton>
-    <SlButton variant="neutral" disabled>Neutral</SlButton>
-    <SlButton variant="warning" disabled>Warning</SlButton>
-    <SlButton variant="danger" disabled>Danger</SlButton>
+    <SlButton variant="default" disabled>
+      Default
+    </SlButton>
+
+    <SlButton variant="primary" disabled>
+      Primary
+    </SlButton>
+
+    <SlButton variant="success" disabled>
+      Success
+    </SlButton>
+
+    <SlButton variant="neutral" disabled>
+      Neutral
+    </SlButton>
+
+    <SlButton variant="warning" disabled>
+      Warning
+    </SlButton>
+
+    <SlButton variant="danger" disabled>
+      Danger
+    </SlButton>
   </>
 );
 ```
@@ -418,7 +501,7 @@ This example demonstrates how to style buttons using a custom class. This is the
     /* Set design tokens for height and border width */
     --sl-input-height-medium: 48px;
     --sl-input-border-width: 4px;
-    
+
     border-radius: 0;
     background-color: #ff1493;
     border-top-color: #ff7ac1;

docs/components/card.md

@@ -2,18 +2,16 @@
 
 [component-header:sl-card]
 
-Cards can be used to group related subjects in a container.
-
 ```html preview
 <sl-card class="card-overview">
-  <img 
-    slot="image" 
-    src="https://images.unsplash.com/photo-1559209172-0ff8f6d49ff7?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=500&q=80" 
+  <img
+    slot="image"
+    src="https://images.unsplash.com/photo-1559209172-0ff8f6d49ff7?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=500&q=80"
     alt="A kitten sits patiently between a terracotta pot and decorative grasses."
-  >
+  />
 
-  <strong>Mittens</strong><br>
-  This kitten is as cute as he is playful. Bring him home today!<br>
+  <strong>Mittens</strong><br />
+  This kitten is as cute as he is playful. Bring him home today!<br />
   <small>6 weeks old</small>
 
   <div slot="footer">
@@ -31,20 +29,16 @@ Cards can be used to group related subjects in a container.
     color: var(--sl-color-neutral-500);
   }
 
-  .card-overview [slot="footer"] {
-    display: flex; 
-    justify-content: space-between; 
+  .card-overview [slot='footer'] {
+    display: flex;
+    justify-content: space-between;
     align-items: center;
   }
 </style>
 ```
 
 ```jsx react
-import { 
-  SlButton, 
-  SlCard, 
-  SlRating 
-} from '@shoelace-style/shoelace/dist/react';
+import { SlButton, SlCard, SlRating } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .card-overview {
@@ -65,18 +59,20 @@ const css = `
 const App = () => (
   <>
     <SlCard className="card-overview">
-      <img 
-        slot="image" 
-        src="https://images.unsplash.com/photo-1559209172-0ff8f6d49ff7?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=500&q=80" 
+      <img
+        slot="image"
+        src="https://images.unsplash.com/photo-1559209172-0ff8f6d49ff7?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=500&q=80"
         alt="A kitten sits patiently between a terracotta pot and decorative grasses."
       />
-
-      <strong>Mittens</strong><br />
-      This kitten is as cute as he is playful. Bring him home today!<br />
+      <strong>Mittens</strong>
+      <br />
+      This kitten is as cute as he is playful. Bring him home today!
+      <br />
       <small>6 weeks old</small>
-
       <div slot="footer">
-        <SlButton variant="primary" pill>More Info</SlButton>
+        <SlButton variant="primary" pill>
+          More Info
+        </SlButton>
         <SlRating></SlRating>
       </div>
     </SlCard>
@@ -132,8 +128,7 @@ Headers can be used to display titles and more.
 <sl-card class="card-header">
   <div slot="header">
     Header Title
-
-    <sl-icon-button name="gear"></sl-icon-button>
+    <sl-icon-button name="gear" label="Settings"></sl-icon-button>
   </div>
 
   This card has a header. You can put all sorts of things in it!
@@ -144,9 +139,9 @@ Headers can be used to display titles and more.
     max-width: 300px;
   }
 
-  .card-header [slot="header"] {
-    display: flex; 
-    align-items: center; 
+  .card-header [slot='header'] {
+    display: flex;
+    align-items: center;
     justify-content: space-between;
   }
 
@@ -188,10 +183,8 @@ const App = () => (
     <SlCard className="card-header">
       <div slot="header">
         Header Title
-
         <SlIconButton name="gear"></SlIconButton>
       </div>
-
       This card has a header. You can put all sorts of things in it!
     </SlCard>
 
@@ -210,7 +203,7 @@ Footers can be used to display actions, summaries, or other relevant content.
 
   <div slot="footer">
     <sl-rating></sl-rating>
-    <sl-button slot="footer" variant="primary">Preview</sl-button>
+    <sl-button variant="primary">Preview</sl-button>
   </div>
 </sl-card>
 
@@ -219,20 +212,16 @@ Footers can be used to display actions, summaries, or other relevant content.
     max-width: 300px;
   }
 
-  .card-footer [slot="footer"] {
-    display: flex; 
-    justify-content: space-between; 
+  .card-footer [slot='footer'] {
+    display: flex;
+    justify-content: space-between;
     align-items: center;
   }
 </style>
 ```
 
 ```jsx react
-import { 
-  SlButton, 
-  SlCard, 
-  SlRating 
-} from '@shoelace-style/shoelace/dist/react';
+import { SlButton, SlCard, SlRating } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .card-footer {
@@ -250,10 +239,11 @@ const App = () => (
   <>
     <SlCard className="card-footer">
       This card has a footer. You can put all sorts of things in it!
-
       <div slot="footer">
         <SlRating></SlRating>
-        <SlButton slot="footer" variant="primary">Preview</SlButton>
+        <SlButton slot="footer" variant="primary">
+          Preview
+        </SlButton>
       </div>
     </SlCard>
 
@@ -268,11 +258,11 @@ Cards accept an `image` slot. The image is displayed atop the card and stretches
 
 ```html preview
 <sl-card class="card-image">
-  <img 
-    slot="image" 
-    src="https://images.unsplash.com/photo-1547191783-94d5f8f6d8b1?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=400&q=80" 
+  <img
+    slot="image"
+    src="https://images.unsplash.com/photo-1547191783-94d5f8f6d8b1?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=400&q=80"
     alt="A kitten walks towards camera on top of pallet."
-  >
+  />
   This is a kitten, but not just any kitten. This kitten likes walking along pallets.
 </sl-card>
 
@@ -295,9 +285,9 @@ const css = `
 const App = () => (
   <>
     <SlCard className="card-image">
-      <img 
-        slot="image" 
-        src="https://images.unsplash.com/photo-1547191783-94d5f8f6d8b1?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=400&q=80" 
+      <img
+        slot="image"
+        src="https://images.unsplash.com/photo-1547191783-94d5f8f6d8b1?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=400&q=80"
         alt="A kitten walks towards camera on top of pallet."
       />
       This is a kitten, but not just any kitten. This kitten likes walking along pallets.

docs/components/carousel-item.md

@@ -0,0 +1,81 @@
+# Carousel Item
+
+[component-header:sl-carousel-item]
+
+```html preview
+<sl-carousel pagination>
+  <sl-carousel-item>
+    <img
+      alt="The sun shines on the mountains and trees - Photo by Adam Kool on Unsplash"
+      src="/assets/examples/carousel/mountains.jpg"
+    />
+  </sl-carousel-item>
+  <sl-carousel-item>
+    <img
+      alt="A waterfall in the middle of a forest - Photo by Thomas Kelly on Unsplash"
+      src="/assets/examples/carousel/waterfall.jpg"
+    />
+  </sl-carousel-item>
+  <sl-carousel-item>
+    <img
+      alt="The sun is setting over a lavender field - Photo by Leonard Cotte on Unsplash"
+      src="/assets/examples/carousel/sunset.jpg"
+    />
+  </sl-carousel-item>
+  <sl-carousel-item>
+    <img
+      alt="A field of grass with the sun setting in the background - Photo by Sapan Patel on Unsplash"
+      src="/assets/examples/carousel/field.jpg"
+    />
+  </sl-carousel-item>
+  <sl-carousel-item>
+    <img
+      alt="A scenic view of a mountain with clouds rolling in - Photo by V2osk on Unsplash"
+      src="/assets/examples/carousel/valley.jpg"
+    />
+  </sl-carousel-item>
+</sl-carousel>
+```
+
+```jsx react
+import { SlCarousel, SlCarouselItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlCarousel pagination>
+    <SlCarouselItem>
+      <img
+        alt="The sun shines on the mountains and trees - Photo by Adam Kool on Unsplash"
+        src="/assets/examples/carousel/mountains.jpg"
+      />
+    </SlCarouselItem>
+    <SlCarouselItem>
+      <img
+        alt="A waterfall in the middle of a forest - Photo by Thomas Kelly on Unsplash"
+        src="/assets/examples/carousel/waterfall.jpg"
+      />
+    </SlCarouselItem>
+    <SlCarouselItem>
+      <img
+        alt="The sun is setting over a lavender field - Photo by Leonard Cotte on Unsplash"
+        src="/assets/examples/carousel/sunset.jpg"
+      />
+    </SlCarouselItem>
+    <SlCarouselItem>
+      <img
+        alt="A field of grass with the sun setting in the background - Photo by Sapan Patel on Unsplash"
+        src="/assets/examples/carousel/field.jpg"
+      />
+    </SlCarouselItem>
+    <SlCarouselItem>
+      <img
+        alt="A scenic view of a mountain with clouds rolling in - Photo by V2osk on Unsplash"
+        src="/assets/examples/carousel/valley.jpg"
+      />
+    </SlCarouselItem>
+  </SlCarousel>
+);
+```
+
+?> Additional demonstrations can be found in the [carousel examples](/components/carousel).
+
+[component-metadata:sl-carousel-item]

docs/components/checkbox.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-checkbox]
 
-Checkboxes allow the user to toggle an option on or off.
-
 ```html preview
 <sl-checkbox>Checkbox</sl-checkbox>
 ```
@@ -11,12 +9,10 @@ Checkboxes allow the user to toggle an option on or off.
 ```jsx react
 import { SlCheckbox } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlCheckbox>Checkbox</SlCheckbox>
-);
+const App = () => <SlCheckbox>Checkbox</SlCheckbox>;
 ```
 
-?> This component doesn't work with standard forms. Use [`<sl-form>`](/components/form) instead.
+?> This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
 
 ## Examples
 
@@ -31,9 +27,7 @@ Use the `checked` attribute to activate the checkbox.
 ```jsx react
 import { SlCheckbox } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlCheckbox checked>Checked</SlCheckbox>
-);
+const App = () => <SlCheckbox checked>Checked</SlCheckbox>;
 ```
 
 ### Indeterminate
@@ -47,9 +41,7 @@ Use the `indeterminate` attribute to make the checkbox indeterminate.
 ```jsx react
 import { SlCheckbox } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlCheckbox indeterminate>Indeterminate</SlCheckbox>
-);
+const App = () => <SlCheckbox indeterminate>Indeterminate</SlCheckbox>;
 ```
 
 ### Disabled
@@ -63,9 +55,102 @@ Use the `disabled` attribute to disable the checkbox.
 ```jsx react
 import { SlCheckbox } from '@shoelace-style/shoelace/dist/react';
 
+const App = () => <SlCheckbox disabled>Disabled</SlCheckbox>;
+```
+
+## Sizes
+
+Use the `size` attribute to change a checkbox's size.
+
+```html preview
+<sl-checkbox size="small">Small</sl-checkbox>
+<br />
+<sl-checkbox size="medium">Medium</sl-checkbox>
+<br />
+<sl-checkbox size="large">Large</sl-checkbox>
+```
+
+```jsx react
+import { SlCheckbox } from '@shoelace-style/shoelace/dist/react';
+
 const App = () => (
-  <SlCheckbox disabled>Disabled</SlCheckbox>
+  <>
+    <SlCheckbox size="small">Small</SlCheckbox>
+    <br />
+    <SlCheckbox size="medium">Medium</SlCheckbox>
+    <br />
+    <SlCheckbox size="large">Large</SlCheckbox>
+  </>
 );
 ```
 
+### Custom Validity
+
+Use the `setCustomValidity()` method to set a custom validation message. This will prevent the form from submitting and make the browser display the error message you provide. To clear the error, call this function with an empty string.
+
+```html preview
+<form class="custom-validity">
+  <sl-checkbox>Check me</sl-checkbox>
+  <br />
+  <sl-button type="submit" variant="primary" style="margin-top: 1rem;">Submit</sl-button>
+</form>
+<script>
+  const form = document.querySelector('.custom-validity');
+  const checkbox = form.querySelector('sl-checkbox');
+  const errorMessage = `Don't forget to check me!`;
+
+  // Set initial validity as soon as the element is defined
+  customElements.whenDefined('sl-checkbox').then(async () => {
+    await checkbox.updateComplete;
+    checkbox.setCustomValidity(errorMessage);
+  });
+
+  // Update validity on change
+  checkbox.addEventListener('sl-change', () => {
+    checkbox.setCustomValidity(checkbox.checked ? '' : errorMessage);
+  });
+
+  // Handle submit
+  form.addEventListener('submit', event => {
+    event.preventDefault();
+    alert('All fields are valid!');
+  });
+</script>
+```
+
+```jsx react
+import { useEffect, useRef } from 'react';
+import { SlButton, SlCheckbox } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const checkbox = useRef(null);
+  const errorMessage = `Don't forget to check me!`;
+
+  function handleChange() {
+    checkbox.current.setCustomValidity(checkbox.current.checked ? '' : errorMessage);
+  }
+
+  function handleSubmit(event) {
+    event.preventDefault();
+    alert('All fields are valid!');
+  }
+
+  useEffect(() => {
+    checkbox.current.setCustomValidity(errorMessage);
+  }, []);
+
+  return (
+    <form class="custom-validity" onSubmit={handleSubmit}>
+      <SlCheckbox ref={checkbox} onSlChange={handleChange}>
+        Check me
+      </SlCheckbox>
+      <br />
+      <SlButton type="submit" variant="primary" style={{ marginTop: '1rem' }}>
+        Submit
+      </SlButton>
+    </form>
+  );
+};
+```
+
 [component-metadata:sl-checkbox]

docs/components/color-picker.md

@@ -2,48 +2,59 @@
 
 [component-header:sl-color-picker]
 
-Color pickers allow the user to select a color.
-
 ```html preview
-<sl-color-picker></sl-color-picker>
+<sl-color-picker label="Select a color"></sl-color-picker>
 ```
 
 ```jsx react
 import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlColorPicker />
-);
+const App = () => <SlColorPicker label="Select a color" />;
 ```
 
+?> This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
+
 ## Examples
 
-### Opacity
+### Initial Value
 
-Use the `opacity` attribute to enable the opacity slider. When this is enabled, the value will be displayed as HEXA, RGBA, or HSLA based on `format`.
+Use the `value` attribute to set an initial value for the color picker.
 
 ```html preview
-<sl-color-picker opacity></sl-color-picker>
+<sl-color-picker value="#4a90e2" label="Select a color"></sl-color-picker>
 ```
 
 ```jsx react
 import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlColorPicker opacity />
-);
+const App = () => <SlColorPicker value="#4a90e2" label="Select a color" />;
+```
+
+### Opacity
+
+Use the `opacity` attribute to enable the opacity slider. When this is enabled, the value will be displayed as HEXA, RGBA, HSLA, or HSVA based on `format`.
+
+```html preview
+<sl-color-picker value="#f5a623ff" opacity label="Select a color"></sl-color-picker>
+```
+
+```jsx react
+import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => <SlColorPicker opacity label="Select a color" />;
 ```
 
 ### Formats
 
-Set the color picker's format with the `format` attribute. Valid options include `hex`, `rgb`, and `hsl`. Note that the color picker's input will accept any parsable format (including CSS color names) regardless of this option.
+Set the color picker's format with the `format` attribute. Valid options include `hex`, `rgb`, `hsl`, and `hsv`. Note that the color picker's input will accept any parsable format (including CSS color names) regardless of this option.
 
 To prevent users from toggling the format themselves, add the `no-format-toggle` attribute.
 
 ```html preview
-<sl-color-picker format="hex" value="#4a90e2"></sl-color-picker>
-<sl-color-picker format="rgb" value="rgb(80, 227, 194)"></sl-color-picker>
-<sl-color-picker format="hsl" value="hsl(290, 87%, 47%)"></sl-color-picker>
+<sl-color-picker format="hex" value="#4a90e2" label="Select a color"></sl-color-picker>
+<sl-color-picker format="rgb" value="rgb(80, 227, 194)" label="Select a color"></sl-color-picker>
+<sl-color-picker format="hsl" value="hsl(290, 87%, 47%)" label="Select a color"></sl-color-picker>
+<sl-color-picker format="hsv" value="hsv(55, 89%, 97%)" label="Select a color"></sl-color-picker>
 ```
 
 ```jsx react
@@ -54,18 +65,47 @@ const App = () => (
     <SlColorPicker format="hex" value="#4a90e2" />
     <SlColorPicker format="rgb" value="rgb(80, 227, 194)" />
     <SlColorPicker format="hsl" value="hsl(290, 87%, 47%)" />
+    <SlColorPicker format="hsv" value="hsv(55, 89%, 97%)" />
   </>
 );
 ```
 
+### Swatches
+
+Use the `swatches` attribute to add convenient presets to the color picker. Any format the color picker can parse is acceptable (including CSS color names), but each value must be separated by a semicolon (`;`). Alternatively, you can pass an array of color values to this property using JavaScript.
+
+```html preview
+<sl-color-picker
+  label="Select a color"
+  swatches="
+    #d0021b; #f5a623; #f8e71c; #8b572a; #7ed321; #417505; #bd10e0; #9013fe; 
+    #4a90e2; #50e3c2; #b8e986; #000; #444; #888; #ccc; #fff;
+  "
+></sl-color-picker>
+```
+
+```jsx react
+import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlColorPicker
+    label="Select a color"
+    swatches="
+      #d0021b; #f5a623; #f8e71c; #8b572a; #7ed321; #417505; #bd10e0; #9013fe; 
+      #4a90e2; #50e3c2; #b8e986; #000; #444; #888; #ccc; #fff;
+    "
+  />
+);
+```
+
 ### Sizes
 
 Use the `size` attribute to change the color picker's trigger size.
 
 ```html preview
-<sl-color-picker size="small"></sl-color-picker>
-<sl-color-picker size="medium"></sl-color-picker>
-<sl-color-picker size="large"></sl-color-picker>
+<sl-color-picker size="small" label="Select a color"></sl-color-picker>
+<sl-color-picker size="medium" label="Select a color"></sl-color-picker>
+<sl-color-picker size="large" label="Select a color"></sl-color-picker>
 ```
 
 ```jsx react
@@ -73,9 +113,9 @@ import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlColorPicker size="small" />
-    <SlColorPicker size="medium" />
-    <SlColorPicker size="large" />
+    <SlColorPicker size="small" label="Select a color" />
+    <SlColorPicker size="medium" label="Select a color" />
+    <SlColorPicker size="large" label="Select a color" />
   </>
 );
 ```
@@ -85,15 +125,13 @@ const App = () => (
 The color picker can be rendered inline instead of in a dropdown using the `inline` attribute.
 
 ```html preview
-<sl-color-picker inline></sl-color-picker>
+<sl-color-picker inline label="Select a color"></sl-color-picker>
 ```
 
 ```jsx react
 import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlColorPicker inline />
-);
+const App = () => <SlColorPicker inline label="Select a color" />;
 ```
 
 [component-metadata:sl-color-picker]

docs/components/details.md

@@ -1,9 +1,9 @@
+<!-- cspell:dictionaries lorem-ipsum -->
+
 # Details
 
 [component-header:sl-details]
 
-Details show a brief summary and expand to show additional content.
-
 ```html preview
 <sl-details summary="Toggle Me">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
@@ -46,6 +46,52 @@ const App = () => (
 );
 ```
 
+### Customizing the Summary Icon
+
+Use the `expand-icon` and `collapse-icon` slots to change the expand and collapse icons, respectively. To disable the animation, override the `rotate` property on the `summary-icon` part as shown below.
+
+```html preview
+<sl-details summary="Toggle Me" class="custom-icons">
+  <sl-icon name="plus-square" slot="expand-icon"></sl-icon>
+  <sl-icon name="dash-square" slot="collapse-icon"></sl-icon>
+
+  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna
+  aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+</sl-details>
+
+<style>
+  sl-details.custom-icons::part(summary-icon) {
+    /* Disable the expand/collapse animation */
+    rotate: none;
+  }
+</style>
+```
+
+```jsx react
+import { SlDetails, SlIcon } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  sl-details.custom-icon::part(summary-icon) {
+    /* Disable the expand/collapse animation */
+    rotate: none;
+  }
+`;
+
+const App = () => (
+  <>
+    <SlDetails summary="Toggle Me" class="custom-icon">
+      <SlIcon name="plus-square" slot="expand-icon" />
+      <SlIcon name="dash-square" slot="collapse-icon" />
+      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore
+      magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
+      consequat.
+    </SlDetails>
+
+    <style>{css}</style>
+  </>
+);
+```
+
 ### Grouping Details
 
 Details are designed to function independently, but you can simulate a group or "accordion" where only one is shown at a time by listening for the `sl-show` event.

docs/components/dialog.md

@@ -1,9 +1,9 @@
+<!-- cspell:dictionaries lorem-ipsum -->
+
 # Dialog
 
 [component-header:sl-dialog]
 
-Dialogs, sometimes called "modals", appear above the page and require the user's immediate attention.
-
 ```html preview
 <sl-dialog label="Dialog" class="dialog-overview">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
@@ -83,12 +83,7 @@ const App = () => {
 
   return (
     <>
-      <SlDialog 
-        label="Dialog" 
-        open={open} 
-        style={{ '--width': '50vw' }} 
-        onSlAfterHide={() => setOpen(false)}
-      >
+      <SlDialog label="Dialog" open={open} style={{ '--width': '50vw' }} onSlAfterHide={() => setOpen(false)}>
         Lorem ipsum dolor sit amet, consectetur adipiscing elit.
         <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
           Close
@@ -135,11 +130,13 @@ const App = () => {
   return (
     <>
       <SlDialog label="Dialog" open={open} onSlAfterHide={() => setOpen(false)}>
-        <div style={{
-          height: '150vh',
-          border: 'dashed 2px var(--sl-color-neutral-200)',
-          padding: '0 1rem'
-        }}>
+        <div
+          style={{
+            height: '150vh',
+            border: 'dashed 2px var(--sl-color-neutral-200)',
+            padding: '0 1rem'
+          }}
+        >
           <p>Scroll down and give it a try! 👇</p>
         </div>
 
@@ -154,16 +151,71 @@ const App = () => {
 };
 ```
 
+### Header Actions
+
+The header shows a functional close button by default. You can use the `header-actions` slot to add additional [icon buttons](/components/icon-button) if needed.
+
+```html preview
+<sl-dialog label="Dialog" class="dialog-header-actions">
+  <sl-icon-button class="new-window" slot="header-actions" name="box-arrow-up-right"></sl-icon-button>
+  Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+  <sl-button slot="footer" variant="primary">Close</sl-button>
+</sl-dialog>
+
+<sl-button>Open Dialog</sl-button>
+
+<script>
+  const dialog = document.querySelector('.dialog-header-actions');
+  const openButton = dialog.nextElementSibling;
+  const closeButton = dialog.querySelector('sl-button[slot="footer"]');
+  const newWindowButton = dialog.querySelector('.new-window');
+
+  openButton.addEventListener('click', () => dialog.show());
+  closeButton.addEventListener('click', () => dialog.hide());
+  newWindowButton.addEventListener('click', () => window.open(location.href));
+</script>
+```
+
+```jsx react
+import { useState } from 'react';
+import { SlButton, SlDialog, SlIconButton } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <SlDialog label="Dialog" open={open} onSlAfterHide={() => setOpen(false)}>
+        <SlIconButton
+          class="new-window"
+          slot="header-actions"
+          name="box-arrow-up-right"
+          onClick={() => window.open(location.href)}
+        />
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+        <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
+          Close
+        </SlButton>
+      </SlDialog>
+
+      <SlButton onClick={() => setOpen(true)}>Open Dialog</SlButton>
+    </>
+  );
+};
+```
+
 ### Preventing the Dialog from Closing
 
 By default, dialogs will close when the user clicks the close button, clicks the overlay, or presses the <kbd>Escape</kbd> key. In most cases, the default behavior is the best behavior in terms of UX. However, there are situations where this may be undesirable, such as when data loss will occur.
 
 To keep the dialog open in such cases, you can cancel the `sl-request-close` event. When canceled, the dialog will remain open and pulse briefly to draw the user's attention to it.
 
+You can use `event.detail.source` to determine what triggered the request to close. This example prevents the dialog from closing when the overlay is clicked, but allows the close button or <kbd>Escape</kbd> to dismiss it.
+
 ```html preview
 <sl-dialog label="Dialog" class="dialog-deny-close">
-  This dialog will not close unless you use the button below.
-  <sl-button slot="footer" variant="primary">Save &amp; Close</sl-button>
+  This dialog will not close when you click on the overlay.
+  <sl-button slot="footer" variant="primary">Close</sl-button>
 </sl-dialog>
 
 <sl-button>Open Dialog</sl-button>
@@ -171,12 +223,17 @@ To keep the dialog open in such cases, you can cancel the `sl-request-close` eve
 <script>
   const dialog = document.querySelector('.dialog-deny-close');
   const openButton = dialog.nextElementSibling;
-  const saveButton = dialog.querySelector('sl-button[slot="footer"]');
+  const closeButton = dialog.querySelector('sl-button[slot="footer"]');
 
   openButton.addEventListener('click', () => dialog.show());
-  saveButton.addEventListener('click', () => dialog.hide());
+  closeButton.addEventListener('click', () => dialog.hide());
 
-  dialog.addEventListener('sl-request-close', event => event.preventDefault());
+  // Prevent the dialog from closing when the user clicks on the overlay
+  dialog.addEventListener('sl-request-close', event => {
+    if (event.detail.source === 'overlay') {
+      event.preventDefault();
+    }
+  });
 </script>
 ```
 
@@ -187,17 +244,19 @@ import { SlButton, SlDialog } from '@shoelace-style/shoelace/dist/react';
 const App = () => {
   const [open, setOpen] = useState(false);
 
+  // Prevent the dialog from closing when the user clicks on the overlay
+  function handleRequestClose(event) {
+    if (event.detail.source === 'overlay') {
+      event.preventDefault();
+    }
+  }
+
   return (
     <>
-      <SlDialog 
-        label="Dialog" 
-        open={open} 
-        onSlRequestClose={event => event.preventDefault()}
-        onSlAfterHide={() => setOpen(false)}
-      >
-        This dialog will not close unless you use the button below.
+      <SlDialog label="Dialog" open={open} onSlRequestClose={handleRequestClose} onSlAfterHide={() => setOpen(false)}>
+        This dialog will not close when you click on the overlay.
         <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
-          Save &amp; Close
+          Close
         </SlButton>
       </SlDialog>
 
@@ -209,11 +268,11 @@ const App = () => {
 
 ### Customizing Initial Focus
 
-By default, the dialog's panel will gain focus when opened. This allows a subsequent tab press to focus on the first tabbable element within the dialog. To set focus on a different element, listen for and cancel the `sl-initial-focus` event.
+By default, the dialog's panel will gain focus when opened. This allows a subsequent tab press to focus on the first tabbable element in the dialog. If you want a different element to have focus, add the `autofocus` attribute to it as shown below.
 
 ```html preview
 <sl-dialog label="Dialog" class="dialog-focus">
-  <sl-input placeholder="I will have focus when the dialog is opened"></sl-input>
+  <sl-input autofocus placeholder="I will have focus when the dialog is opened"></sl-input>
   <sl-button slot="footer" variant="primary">Close</sl-button>
 </sl-dialog>
 
@@ -227,40 +286,20 @@ By default, the dialog's panel will gain focus when opened. This allows a subseq
 
   openButton.addEventListener('click', () => dialog.show());
   closeButton.addEventListener('click', () => dialog.hide());
-
-  dialog.addEventListener('sl-initial-focus', event => {
-    event.preventDefault();
-    input.focus({ preventScroll: true });
-  });
 </script>
 ```
 
 ```jsx react
-import { useRef, useState } from 'react';
-import { 
-  SlButton, 
-  SlDialog, 
-  SlInput 
-} from '@shoelace-style/shoelace/dist/react';
+import { useState } from 'react';
+import { SlButton, SlDialog, SlInput } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
-  const input = useRef(null);
   const [open, setOpen] = useState(false);
 
-  function handleInitialFocus(event) {
-    event.preventDefault();
-    input.current.focus();
-  }
-
   return (
     <>
-      <SlDialog 
-        label="Dialog" 
-        open={open} 
-        onSlInitialFocus={handleInitialFocus}
-        onSlAfterHide={() => setOpen(false)}
-      >
-        <SlInput ref={input} placeholder="I will have focus when the dialog is opened" />
+      <SlDialog label="Dialog" open={open} onSlAfterHide={() => setOpen(false)}>
+        <SlInput autofocus placeholder="I will have focus when the dialog is opened" />
         <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
           Close
         </SlButton>
@@ -272,4 +311,6 @@ const App = () => {
 };
 ```
 
+?> You can further customize initial focus behavior by canceling the `sl-initial-focus` event and setting focus yourself inside the event handler.
+
 [component-metadata:sl-dialog]

docs/components/divider.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-divider]
 
-Dividers are used to visually separate or group elements.
-
 ```html preview
 <sl-divider></sl-divider>
 ```
@@ -11,10 +9,9 @@ Dividers are used to visually separate or group elements.
 ```jsx react
 import { SlDivider } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlDivider />
-);
+const App = () => <SlDivider />;
 ```
+
 ## Examples
 
 ### Width
@@ -28,9 +25,7 @@ Use the `--width` custom property to change the width of the divider.
 ```jsx react
 import { SlDivider } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlDivider style={{ '--width': '4px' }} />
-);
+const App = () => <SlDivider style={{ '--width': '4px' }} />;
 ```
 
 ### Color
@@ -44,9 +39,7 @@ Use the `--color` custom property to change the color of the divider.
 ```jsx react
 import { SlDivider } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlDivider style={{ '--color': 'tomato' }} />
-);
+const App = () => <SlDivider style={{ '--color': 'tomato' }} />;
 ```
 
 ### Spacing
@@ -91,10 +84,10 @@ Add the `vertical` attribute to draw the divider in a vertical orientation. The
 import { SlDivider } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <div 
-    style={{ 
-      display: 'flex', 
-      alignItems: 'center', 
+  <div
+    style={{
+      display: 'flex',
+      alignItems: 'center',
       height: '2rem'
     }}
   >
@@ -112,7 +105,7 @@ const App = () => (
 Use dividers in [menus](/components/menu) to visually group menu items.
 
 ```html preview
-<sl-menu style="max-width: 200px; border: solid 1px var(--sl-panel-border-color); background: var(--sl-panel-background-color); border-radius: var(--sl-border-radius-medium);">
+<sl-menu style="max-width: 200px;">
   <sl-menu-item value="1">Option 1</sl-menu-item>
   <sl-menu-item value="2">Option 2</sl-menu-item>
   <sl-menu-item value="3">Option 3</sl-menu-item>
@@ -124,20 +117,10 @@ Use dividers in [menus](/components/menu) to visually group menu items.
 ```
 
 ```jsx react
-import { 
-  SlDivider, 
-  SlMenu, 
-  SlMenuItem 
-} from '@shoelace-style/shoelace/dist/react';
+import { SlDivider, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlMenu 
-    style={{
-      maxWidth: '200px',
-      border: 'solid 1px var(--sl-panel-border-color)',
-      borderRadius: 'var(--sl-border-radius-medium)'
-    }}
-  >
+  <SlMenu style={{ maxWidth: '200px' }}>
     <SlMenuItem value="1">Option 1</SlMenuItem>
     <SlMenuItem value="2">Option 2</SlMenuItem>
     <SlMenuItem value="3">Option 3</SlMenuItem>

docs/components/drawer.md

@@ -1,9 +1,9 @@
+<!-- cspell:dictionaries lorem-ipsum -->
+
 # Drawer
 
 [component-header:sl-drawer]
 
-Drawers slide in from a container to expose additional options and information.
-
 ```html preview
 <sl-drawer label="Drawer" class="drawer-overview">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
@@ -77,12 +77,7 @@ const App = () => {
 
   return (
     <>
-      <SlDrawer 
-        label="Drawer" 
-        placement="start" 
-        open={open} 
-        onSlAfterHide={() => setOpen(false)}
-      >
+      <SlDrawer label="Drawer" placement="start" open={open} onSlAfterHide={() => setOpen(false)}>
         This drawer slides in from the start.
         <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
           Close
@@ -126,12 +121,7 @@ const App = () => {
 
   return (
     <>
-      <SlDrawer 
-        label="Drawer" 
-        placement="top" 
-        open={open} 
-        onSlAfterHide={() => setOpen(false)}
-      >
+      <SlDrawer label="Drawer" placement="top" open={open} onSlAfterHide={() => setOpen(false)}>
         This drawer slides in from the top.
         <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
           Close
@@ -175,12 +165,7 @@ const App = () => {
 
   return (
     <>
-      <SlDrawer 
-        label="Drawer" 
-        placement="bottom" 
-        open={open} 
-        onSlAfterHide={() => setOpen(false)}
-      >
+      <SlDrawer label="Drawer" placement="bottom" open={open} onSlAfterHide={() => setOpen(false)}>
         This drawer slides in from the bottom.
         <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
           Close
@@ -195,7 +180,9 @@ const App = () => {
 
 ### Contained to an Element
 
-By default, the drawer slides out of its [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block#Identifying_the_containing_block), which is usually the viewport. To make the drawer slide out of its parent element, add the `contained` attribute and `position: relative` to the parent.
+By default, drawers slide out of their [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block#Identifying_the_containing_block), which is usually the viewport. To make a drawer slide out of a parent element, add the `contained` attribute to the drawer and apply `position: relative` to its parent.
+
+Unlike normal drawers, contained drawers are not modal. This means they do not show an overlay, they do not trap focus, and they are not dismissible with <kbd>Escape</kbd>. This is intentional to allow users to interact with elements outside of the drawer.
 
 ```html preview
 <div
@@ -209,14 +196,14 @@ By default, the drawer slides out of its [containing block](https://developer.mo
   </sl-drawer>
 </div>
 
-<sl-button>Open Drawer</sl-button>
+<sl-button>Toggle Drawer</sl-button>
 
 <script>
   const drawer = document.querySelector('.drawer-contained');
   const openButton = drawer.parentElement.nextElementSibling;
   const closeButton = drawer.querySelector('sl-button[variant="primary"]');
 
-  openButton.addEventListener('click', () => drawer.show());
+  openButton.addEventListener('click', () => (drawer.open = !drawer.open));
   closeButton.addEventListener('click', () => drawer.hide());
 </script>
 ```
@@ -239,12 +226,13 @@ const App = () => {
           marginBottom: '1rem'
         }}
       >
-        The drawer will be contained to this box. This content won't shift or be affected in any way when the drawer opens.
-
+        The drawer will be contained to this box. This content won't shift or be affected in any way when the drawer
+        opens.
         <SlDrawer
-          label="Drawer" 
-          contained 
-          open={open} 
+          label="Drawer"
+          contained
+          no-modal
+          open={open}
           onSlAfterHide={() => setOpen(false)}
           style={{ '--size': '50%' }}
         >
@@ -292,11 +280,7 @@ const App = () => {
 
   return (
     <>
-      <SlDrawer 
-        label="Drawer" 
-        open={open} onSlAfterHide={() => setOpen(false)}
-        style={{ '--size': '50vw' }}
-      >
+      <SlDrawer label="Drawer" open={open} onSlAfterHide={() => setOpen(false)} style={{ '--size': '50vw' }}>
         This drawer is always 50% of the viewport.
         <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
           Close
@@ -343,7 +327,7 @@ const App = () => {
   return (
     <>
       <SlDrawer label="Drawer" open={open} onSlAfterHide={() => setOpen(false)}>
-        <div 
+        <div
           style={{
             height: '150vh',
             border: 'dashed 2px var(--sl-color-neutral-200)',
@@ -363,17 +347,66 @@ const App = () => {
 };
 ```
 
+### Header Actions
+
+The header shows a functional close button by default. You can use the `header-actions` slot to add additional [icon buttons](/components/icon-button) if needed.
+
+```html preview
+<sl-drawer label="Drawer" class="drawer-header-actions">
+  <sl-icon-button class="new-window" slot="header-actions" name="box-arrow-up-right"></sl-icon-button>
+  Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+  <sl-button slot="footer" variant="primary">Close</sl-button>
+</sl-drawer>
+
+<sl-button>Open Drawer</sl-button>
+
+<script>
+  const drawer = document.querySelector('.drawer-header-actions');
+  const openButton = drawer.nextElementSibling;
+  const closeButton = drawer.querySelector('sl-button[variant="primary"]');
+  const newWindowButton = drawer.querySelector('.new-window');
+
+  openButton.addEventListener('click', () => drawer.show());
+  closeButton.addEventListener('click', () => drawer.hide());
+  newWindowButton.addEventListener('click', () => window.open(location.href));
+</script>
+```
+
+```jsx react
+import { useState } from 'react';
+import { SlButton, SlDrawer, SlIconButton } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <SlDrawer label="Drawer" open={open} onSlAfterHide={() => setOpen(false)}>
+        <SlIconButton slot="header-actions" name="box-arrow-up-right" onClick={() => window.open(location.href)} />
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+        <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
+          Close
+        </SlButton>
+      </SlDrawer>
+
+      <SlButton onClick={() => setOpen(true)}>Open Drawer</SlButton>
+    </>
+  );
+};
+```
+
 ### Preventing the Drawer from Closing
 
 By default, drawers will close when the user clicks the close button, clicks the overlay, or presses the <kbd>Escape</kbd> key. In most cases, the default behavior is the best behavior in terms of UX. However, there are situations where this may be undesirable, such as when data loss will occur.
 
 To keep the drawer open in such cases, you can cancel the `sl-request-close` event. When canceled, the drawer will remain open and pulse briefly to draw the user's attention to it.
 
+You can use `event.detail.source` to determine what triggered the request to close. This example prevents the drawer from closing when the overlay is clicked, but allows the close button or <kbd>Escape</kbd> to dismiss it.
 
 ```html preview
 <sl-drawer label="Drawer" class="drawer-deny-close">
-  This drawer will not close unless you use the button below.
-  <sl-button slot="footer" variant="primary">Save &amp; Close</sl-button>
+  This drawer will not close when you click on the overlay.
+  <sl-button slot="footer" variant="primary">Close</sl-button>
 </sl-drawer>
 
 <sl-button>Open Drawer</sl-button>
@@ -386,7 +419,12 @@ To keep the drawer open in such cases, you can cancel the `sl-request-close` eve
   openButton.addEventListener('click', () => drawer.show());
   closeButton.addEventListener('click', () => drawer.hide());
 
-  drawer.addEventListener('sl-request-close', event => event.preventDefault());
+  // Prevent the drawer from closing when the user clicks on the overlay
+  drawer.addEventListener('sl-request-close', event => {
+    if (event.detail.source === 'overlay') {
+      event.preventDefault();
+    }
+  });
 </script>
 ```
 
@@ -397,15 +435,17 @@ import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react';
 const App = () => {
   const [open, setOpen] = useState(false);
 
+  // Prevent the drawer from closing when the user clicks on the overlay
+  function handleRequestClose(event) {
+    if (event.detail.source === 'overlay') {
+      event.preventDefault();
+    }
+  }
+
   return (
     <>
-      <SlDrawer 
-        label="Drawer" 
-        open={open} 
-        onSlRequestClose={event => event.preventDefault()}
-        onSlAfterHide={() => setOpen(false)}
-      >
-        This drawer will not close unless you use the button below.
+      <SlDrawer label="Drawer" open={open} onSlRequestClose={handleRequestClose} onSlAfterHide={() => setOpen(false)}>
+        This drawer will not close when you click on the overlay.
         <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
           Save &amp; Close
         </SlButton>
@@ -419,11 +459,11 @@ const App = () => {
 
 ### Customizing Initial Focus
 
-By default, the drawer's panel will gain focus when opened. This allows the first tab press to focus on the first tabbable element within the drawer. To set focus on a different element, listen for and cancel the `sl-initial-focus` event.
+By default, the drawer's panel will gain focus when opened. This allows a subsequent tab press to focus on the first tabbable element in the drawer. If you want a different element to have focus, add the `autofocus` attribute to it as shown below.
 
 ```html preview
 <sl-drawer label="Drawer" class="drawer-focus">
-  <sl-input placeholder="I will have focus when the drawer is opened"></sl-input>
+  <sl-input autofocus placeholder="I will have focus when the drawer is opened"></sl-input>
   <sl-button slot="footer" variant="primary">Close</sl-button>
 </sl-drawer>
 
@@ -437,40 +477,20 @@ By default, the drawer's panel will gain focus when opened. This allows the firs
 
   openButton.addEventListener('click', () => drawer.show());
   closeButton.addEventListener('click', () => drawer.hide());
-
-  drawer.addEventListener('sl-initial-focus', event => {
-    event.preventDefault();
-    input.focus({ preventScroll: true });
-  });    
 </script>
 ```
 
 ```jsx react
-import { useRef, useState } from 'react';
-import { 
-  SlButton, 
-  SlDrawer, 
-  SlInput 
-} from '@shoelace-style/shoelace/dist/react';
+import { useState } from 'react';
+import { SlButton, SlDrawer, SlInput } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
-  const input = useRef(null);
   const [open, setOpen] = useState(false);
 
-  function handleInitialFocus(event) {
-    event.preventDefault();
-    input.current.focus();
-  }
-
   return (
     <>
-      <SlDrawer 
-        label="Drawer" 
-        open={open} 
-        onSlInitialFocus={handleInitialFocus}
-        onSlAfterHide={() => setOpen(false)}
-      >
-        <SlInput ref={input} placeholder="I will have focus when the drawer is opened" />
+      <SlDrawer label="Drawer" open={open} onSlAfterHide={() => setOpen(false)}>
+        <SlInput autofocus placeholder="I will have focus when the drawer is opened" />
         <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
           Close
         </SlButton>
@@ -482,4 +502,5 @@ const App = () => {
 };
 ```
 
+?> You can further customize initial focus behavior by canceling the `sl-initial-focus` event and setting focus yourself inside the event handler.
 [component-metadata:sl-drawer]

docs/components/dropdown.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-dropdown]
 
-Dropdowns expose additional content that "drops down" in a panel.
-
 Dropdowns consist of a trigger and a panel. By default, activating the trigger will expose the panel and interacting outside of the panel will close it.
 
 Dropdowns are designed to work well with [menus](/components/menu) to provide a list of options the user can select from. However, dropdowns can also be used in lower-level applications (e.g. [color picker](/components/color-picker) and [select](/components/select)). The API gives you complete control over showing, hiding, and positioning the panel.
@@ -16,7 +14,7 @@ Dropdowns are designed to work well with [menus](/components/menu) to provide a
     <sl-menu-item>Dropdown Item 2</sl-menu-item>
     <sl-menu-item>Dropdown Item 3</sl-menu-item>
     <sl-divider></sl-divider>
-    <sl-menu-item checked>Checked</sl-menu-item>
+    <sl-menu-item type="checkbox" checked>Checkbox</sl-menu-item>
     <sl-menu-item disabled>Disabled</sl-menu-item>
     <sl-divider></sl-divider>
     <sl-menu-item>
@@ -32,24 +30,21 @@ Dropdowns are designed to work well with [menus](/components/menu) to provide a
 ```
 
 ```jsx react
-import { 
-  SlButton,
-  SlDivider,
-  SlDropdown,
-  SlIcon,
-  SlMenu,
-  SlMenuItem
-} from '@shoelace-style/shoelace/dist/react';
+import { SlButton, SlDivider, SlDropdown, SlIcon, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlDropdown>
-    <SlButton slot="trigger" caret>Dropdown</SlButton>
+    <SlButton slot="trigger" caret>
+      Dropdown
+    </SlButton>
     <SlMenu>
       <SlMenuItem>Dropdown Item 1</SlMenuItem>
       <SlMenuItem>Dropdown Item 2</SlMenuItem>
       <SlMenuItem>Dropdown Item 3</SlMenuItem>
       <SlDivider />
-      <SlMenuItem checked>Checked</SlMenuItem>
+      <SlMenuItem type="checkbox" checked>
+        Checkbox
+      </SlMenuItem>
       <SlMenuItem disabled>Disabled</SlMenuItem>
       <SlDivider />
       <SlMenuItem>
@@ -61,7 +56,7 @@ const App = () => (
         <SlIcon slot="suffix" name="heart" />
       </SlMenuItem>
     </SlMenu>
-  </SlDropdown>  
+  </SlDropdown>
 );
 ```
 
@@ -69,7 +64,7 @@ const App = () => (
 
 ### Getting the Selected Item
 
-When dropdowns are used with [menus](/components/menu), you can listen for the `sl-select` event to determine which menu item was selected. The menu item element will be exposed in `event.detail.item`. You can set `value` props to make it easier to identify commands.
+When dropdowns are used with [menus](/components/menu), you can listen for the [`sl-select`](/components/menu#events) event to determine which menu item was selected. The menu item element will be exposed in `event.detail.item`. You can set `value` props to make it easier to identify commands.
 
 ```html preview
 <div class="dropdown-selection">
@@ -95,12 +90,7 @@ When dropdowns are used with [menus](/components/menu), you can listen for the `
 ```
 
 ```jsx react
-import { 
-  SlButton,
-  SlDropdown,
-  SlMenu,
-  SlMenuItem
-} from '@shoelace-style/shoelace/dist/react';
+import { SlButton, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   function handleSelect(event) {
@@ -110,13 +100,15 @@ const App = () => {
 
   return (
     <SlDropdown>
-      <SlButton slot="trigger" caret>Edit</SlButton>
+      <SlButton slot="trigger" caret>
+        Edit
+      </SlButton>
       <SlMenu onSlSelect={handleSelect}>
         <SlMenuItem value="cut">Cut</SlMenuItem>
         <SlMenuItem value="copy">Copy</SlMenuItem>
         <SlMenuItem value="paste">Paste</SlMenuItem>
       </SlMenu>
-    </SlDropdown> 
+    </SlDropdown>
   );
 };
 ```
@@ -148,12 +140,7 @@ Alternatively, you can listen for the `click` event on individual menu items. No
 ```
 
 ```jsx react
-import { 
-  SlButton,
-  SlDropdown,
-  SlMenu,
-  SlMenuItem
-} from '@shoelace-style/shoelace/dist/react';
+import { SlButton, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   function handleCut() {
@@ -170,13 +157,15 @@ const App = () => {
 
   return (
     <SlDropdown>
-      <SlButton slot="trigger" caret>Edit</SlButton>
+      <SlButton slot="trigger" caret>
+        Edit
+      </SlButton>
       <SlMenu>
         <SlMenuItem onClick={handleCut}>Cut</SlMenuItem>
         <SlMenuItem onClick={handleCopy}>Copy</SlMenuItem>
         <SlMenuItem onClick={handlePaste}>Paste</SlMenuItem>
       </SlMenu>
-    </SlDropdown> 
+    </SlDropdown>
   );
 };
 ```
@@ -200,17 +189,13 @@ The preferred placement of the dropdown can be set with the `placement` attribut
 ```
 
 ```jsx react
-import { 
-  SlButton,
-  SlDivider,
-  SlDropdown,
-  SlMenu,
-  SlMenuItem
-} from '@shoelace-style/shoelace/dist/react';
+import { SlButton, SlDivider, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlDropdown placement="top-start">
-    <SlButton slot="trigger" caret>Edit</SlButton>
+    <SlButton slot="trigger" caret>
+      Edit
+    </SlButton>
     <SlMenu>
       <SlMenuItem>Cut</SlMenuItem>
       <SlMenuItem>Copy</SlMenuItem>
@@ -219,7 +204,7 @@ const App = () => (
       <SlMenuItem>Find</SlMenuItem>
       <SlMenuItem>Replace</SlMenuItem>
     </SlMenu>
-  </SlDropdown> 
+  </SlDropdown>
 );
 ```
 
@@ -242,17 +227,13 @@ The distance from the panel to the trigger can be customized using the `distance
 ```
 
 ```jsx react
-import { 
-  SlButton,
-  SlDivider,
-  SlDropdown,
-  SlMenu,
-  SlMenuItem
-} from '@shoelace-style/shoelace/dist/react';
+import { SlButton, SlDivider, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlDropdown distance={30}>
-    <SlButton slot="trigger" caret>Edit</SlButton>
+    <SlButton slot="trigger" caret>
+      Edit
+    </SlButton>
     <SlMenu>
       <SlMenuItem>Cut</SlMenuItem>
       <SlMenuItem>Copy</SlMenuItem>
@@ -261,7 +242,7 @@ const App = () => (
       <SlMenuItem>Find</SlMenuItem>
       <SlMenuItem>Replace</SlMenuItem>
     </SlMenu>
-  </SlDropdown> 
+  </SlDropdown>
 );
 ```
 
@@ -284,17 +265,13 @@ The offset of the panel along the trigger can be customized using the `skidding`
 ```
 
 ```jsx react
-import { 
-  SlButton,
-  SlDivider,
-  SlDropdown,
-  SlMenu,
-  SlMenuItem
-} from '@shoelace-style/shoelace/dist/react';
+import { SlButton, SlDivider, SlDropdown, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlDropdown skidding={30}>
-    <SlButton slot="trigger" caret>Edit</SlButton>
+    <SlButton slot="trigger" caret>
+      Edit
+    </SlButton>
     <SlMenu>
       <SlMenuItem>Cut</SlMenuItem>
       <SlMenuItem>Copy</SlMenuItem>
@@ -303,7 +280,7 @@ const App = () => (
       <SlMenuItem>Find</SlMenuItem>
       <SlMenuItem>Replace</SlMenuItem>
     </SlMenu>
-  </SlDropdown> 
+  </SlDropdown>
 );
 ```
 
@@ -334,6 +311,7 @@ Dropdown panels will be clipped if they're inside a container that has `overflow
 
 <style>
   .dropdown-hoist {
+    position: relative;
     border: solid 2px var(--sl-panel-border-color);
     padding: var(--sl-spacing-medium);
     overflow: hidden;
@@ -342,14 +320,7 @@ Dropdown panels will be clipped if they're inside a container that has `overflow
 ```
 
 ```jsx react
-import { 
-  SlButton,
-  SlDivider,
-  SlDropdown,
-  SlIcon,
-  SlMenu,
-  SlMenuItem
-} from '@shoelace-style/shoelace/dist/react';
+import { SlButton, SlDivider, SlDropdown, SlIcon, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const css = `
   .dropdown-hoist {
@@ -363,7 +334,9 @@ const App = () => (
   <>
     <div className="dropdown-hoist">
       <SlDropdown>
-        <SlButton slot="trigger" caret>No Hoist</SlButton>
+        <SlButton slot="trigger" caret>
+          No Hoist
+        </SlButton>
         <SlMenu>
           <SlMenuItem>Item 1</SlMenuItem>
           <SlMenuItem>Item 2</SlMenuItem>
@@ -372,7 +345,9 @@ const App = () => (
       </SlDropdown>
 
       <SlDropdown hoist>
-        <SlButton slot="trigger" caret>Hoist</SlButton>
+        <SlButton slot="trigger" caret>
+          Hoist
+        </SlButton>
         <SlMenu>
           <SlMenuItem>Item 1</SlMenuItem>
           <SlMenuItem>Item 2</SlMenuItem>

docs/components/form.md

@@ -1,449 +0,0 @@
-# Form
-
-[component-header:sl-form]
-
-Forms collect data that can easily be processed and sent to a server.
-
-All Shoelace components make use of a [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) to encapsulate markup, styles, and behavior. One caveat of this approach is that native `<form>` elements will not recognize Shoelace form controls.
-
-This component solves that problem by serializing _both_ Shoelace form controls and native form controls when the form is submitted. The resulting form data is exposed in the `sl-submit` event as a [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) object in `event.detail.formData`. You can also find an array of form controls in `event.detail.formControls`.
-
-Shoelace forms don't make use of `action` and `method` attributes and they don't submit the same way as native forms. To handle submission, you need to listen for the `sl-submit` event as shown in the example below and make an XHR request with the resulting form data.
-
-```html preview
-<sl-form class="form-overview">
-  <sl-input name="name" variant="text" label="Name"></sl-input>
-  <br>
-  <sl-select name="favorite" label="Select your favorite">
-    <sl-menu-item value="birds">Birds</sl-menu-item>
-    <sl-menu-item value="cats">Cats</sl-menu-item>
-    <sl-menu-item value="dogs">Dogs</sl-menu-item>
-  </sl-select>
-  <br>
-  <sl-checkbox name="agree" value="yes">
-    I totally agree
-  </sl-checkbox>
-  <br><br>
-  <sl-button submit>Submit</sl-button>
-</sl-form>
-
-<script>
-  const form = document.querySelector('.form-overview');
-
-  form.addEventListener('sl-submit', event => {
-    const formData = event.detail.formData;
-    let output = '';
-
-    // Post data to a server and wait for a JSON response
-    fetch('https://jsonplaceholder.typicode.com/posts', {
-      method: 'POST',
-      body: formData
-    })
-    .then(response => response.json())
-    .then(result => {
-      console.log('Success:', result);
-    })
-    .catch(error => {
-      console.error('Error:', error);
-    });
-  });
-</script>
-```
-
-```jsx react
-import { 
-  SlButton,
-  SlCheckbox, 
-  SlForm, 
-  SlInput,
-  SlMenuItem, 
-  SlSelect,
-} from '@shoelace-style/shoelace/dist/react';
-
-function handleSubmit(event) {
-  let output = '';
-
-  // Post data to a server and wait for a JSON response
-  fetch('https://jsonplaceholder.typicode.com/posts', {
-    method: 'POST',
-    body: event.detail.formData
-  })
-  .then(response => response.json())
-  .then(result => {
-    console.log('Success:', result);
-  })
-  .catch(error => {
-    console.error('Error:', error);
-  });
-}
-
-const App = () => (
-  <SlForm onSlSubmit={handleSubmit}>
-    <SlInput name="name" variant="text" label="Name" />
-    <br />
-    <SlSelect name="favorite" label="Select your favorite">
-      <SlMenuItem value="birds">Birds</SlMenuItem>
-      <SlMenuItem value="cats">Cats</SlMenuItem>
-      <SlMenuItem value="dogs">Dogs</SlMenuItem>
-    </SlSelect>
-    <br />
-    <SlCheckbox name="agree" value="yes">
-      I totally agree
-    </SlCheckbox>
-    <br /><br />
-    <SlButton submit>Submit</SlButton>
-  </SlForm>
-);
-```
-
-## Handling Submissions
-
-### Using Form Data
-
-On submit, a [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) object will be attached to `event.detail.formData`. You can use this along with [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/fetch) to pass data to the server.
-
-```html preview
-<sl-form class="form-formdata">
-  <sl-input name="name" variant="text" label="Name" required></sl-input>
-  <sl-input name="age" variant="number" label="Age" required></sl-input>
-  <br>
-  <sl-button submit>Submit</sl-button>
-</sl-form>
-
-<script>
-  const form = document.querySelector('.form-formdata');
-
-  form.addEventListener('sl-submit', event => {
-    fetch('https://jsonplaceholder.typicode.com/posts', {
-      method: 'POST',
-      body: event.detail.formData
-    }).then(res => {
-      console.log(res);
-    }).catch(err => {
-      console.error(err);
-    });
-  });
-</script>
-```
-
-```jsx react
-import {
-  SlButton, 
-  SlForm, 
-  SlInput 
-} from '@shoelace-style/shoelace/dist/react';
-
-const App = () => {
-  function handleSubmit(event) {
-    fetch('https://jsonplaceholder.typicode.com/posts', {
-      method: 'POST',
-      body: event.detail.formData
-    }).then(res => {
-      console.log(res);
-    }).catch(err => {
-      console.error(err);
-    });    
-  }
-
-  return (
-    <SlForm class="form-formdata" onSlSubmit={handleSubmit}>
-      <SlInput name="name" variant="text" label="Name" required />
-      <SlInput name="age" variant="number" label="Age" required />
-      <br />
-      <SlButton submit>Submit</SlButton>
-    </SlForm>
-  );
-};
-```
-
-### Converting Form Data to JSON
-
-It's sometimes useful to have form values in a plain object or a JSON string. You can convert the submitted `FormData` object to JSON by iterating and placing the name/value pairs in an object.
-
-```js
-form.addEventListener('sl-submit', event => {
-  const json = {};
-  event.detail.formData.forEach((value, key) => (json[key] = value));
-
-  console.log(JSON.stringify(json));
-});
-```
-
-## Form Control Validation
-
-Client-side validation can be enabled through the browser's [Constraint Validation API](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation) for many form controls. You can enable it using props such as `required`, `pattern`, `minlength`, and `maxlength`. As the user interacts with the form control, the `invalid` attribute will reflect its validity based on its current value and the constraints that have been defined.
-
-When a form control is invalid, the containing form will not be submitted. Instead, the browser will show the user a relevant error message. If you don't want to use client-side validation, you can suppress this behavior by adding `novalidate` to the `<sl-form>` element.
-
-All form controls support validation, but not all validation props are available for every component. Refer to a component's documentation to see which validation props it supports.
-
-!> Client-side validation can be used to improve the UX of forms, but it is not a replacement for server-side validation. **You should always validate and sanitize user input on the server!**
-
-### Required Fields
-
-To make a field required, use the `required` prop. The form will not be submitted if a required form control is empty.
-
-```html preview
-<sl-form class="input-validation-required">
-  <sl-input name="name" label="Name" required></sl-input>
-  <br>
-  <sl-select label="Favorite Animal" clearable required>
-    <sl-menu-item value="birds">Birds</sl-menu-item>
-    <sl-menu-item value="cats">Cats</sl-menu-item>
-    <sl-menu-item value="dogs">Dogs</sl-menu-item>
-    <sl-menu-item value="other">Other</sl-menu-item>
-  </sl-select>
-  <br>
-  <sl-textarea name="comment" label="Comment" required></sl-textarea>
-  <br>
-  <sl-checkbox required>Check me before submitting</sl-checkbox>
-  <br><br>
-  <sl-button variant="primary" submit>Submit</sl-button>
-</sl-form>
-
-<script>
-  const form = document.querySelector('.input-validation-required');
-  form.addEventListener('sl-submit', () => alert('All fields are valid!'));
-</script>
-```
-
-```jsx react
-import { 
-  SlButton,
-  SlCheckbox, 
-  SlForm, 
-  SlInput,
-  SlMenuItem, 
-  SlSelect,
-  SlTextarea
-} from '@shoelace-style/shoelace/dist/react';
-
-const App = () => (
-  <SlForm onSlSubmit={() => alert('All fields are valid!')}>
-    <SlInput name="name" label="Name" required />
-    <br />
-    <SlSelect label="Favorite Animal" clearable required>
-      <SlMenuItem value="birds">Birds</SlMenuItem>
-      <SlMenuItem value="cats">Cats</SlMenuItem>
-      <SlMenuItem value="dogs">Dogs</SlMenuItem>
-      <SlMenuItem value="other">Other</SlMenuItem>
-    </SlSelect>
-    <br />
-    <SlTextarea name="comment" label="Comment" required></SlTextarea>
-    <br />
-    <SlCheckbox required>Check me before submitting</SlCheckbox>
-    <br /><br />
-    <SlButton variant="primary" submit>Submit</SlButton>
-  </SlForm>
-);
-```
-
-### Input Patterns
-
-To restrict a value to a specific [pattern](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern), use the `pattern` attribute. This example only allows the letters A-Z, so the form will not submit if a number or symbol is entered. This only works with `<sl-input>` elements.
-
-```html preview
-<sl-form class="input-validation-pattern">
-  <sl-input name="letters" required label="Letters" pattern="[A-Za-z]+"></sl-input>
-  <br>
-  <sl-button variant="primary" submit>Submit</sl-button>
-</sl-form>
-
-<script>
-  const form = document.querySelector('.input-validation-pattern');
-  form.addEventListener('sl-submit', () => alert('All fields are valid!'));
-</script>
-```
-
-```jsx react
-import { 
-  SlButton,
-  SlForm, 
-  SlInput
-} from '@shoelace-style/shoelace/dist/react';
-
-const App = () => (
-  <SlForm onSlSubmit={() => alert('All fields are valid!')}>
-    <SlInput name="letters" required label="Letters" pattern="[A-Za-z]+" />
-    <br />
-    <SlButton variant="primary" submit>Submit</SlButton>
-  </SlForm>
-);
-```
-
-### Input Types
-
-Some input types will automatically trigger constraints, such as `email` and `url`.
-
-```html preview
-<sl-form class="input-validation-type">
-  <sl-input variant="email" label="Email" placeholder="you@example.com" required></sl-input>
-  <br>
-  <sl-input variant="url" label="URL" placeholder="https://example.com/" required></sl-input>
-  <br>
-  <sl-button variant="primary" submit>Submit</sl-button>
-</sl-form>
-
-<script>
-  const form = document.querySelector('.input-validation-type');
-  form.addEventListener('sl-submit', () => alert('All fields are valid!'));
-</script>
-```
-
-```jsx react
-import { 
-  SlButton,
-  SlForm, 
-  SlInput
-} from '@shoelace-style/shoelace/dist/react';
-
-const App = () => (
-  <SlForm onSlSubmit={() => alert('All fields are valid!')}>
-    <SlInput variant="email" label="Email" placeholder="you@example.com" required />
-    <br />
-    <SlInput variant="url" label="URL" placeholder="https://example.com/" required />
-    <br />
-    <SlButton variant="primary" submit>Submit</SlButton>
-  </SlForm>
-);
-```
-
-### Custom Validation
-
-To create a custom validation error, use the `setCustomValidity` method. The form will not be submitted when this method is called with anything other than an empty string, and its message will be shown by the browser as the validation error. To make the input valid again, call the method a second time with an empty string as the argument.
-
-```html preview
-<sl-form class="input-validation-custom">
-  <sl-input label="Type 'shoelace'" required></sl-input>
-  <br>
-  <sl-button variant="primary" submit>Submit</sl-button>
-</sl-form>
-
-<script>
-  const form = document.querySelector('.input-validation-custom');
-  const input = form.querySelector('sl-input');
-
-  form.addEventListener('sl-submit', () => alert('All fields are valid!'));
-  input.addEventListener('sl-input', () => {
-    if (input.value === 'shoelace') {
-      input.setCustomValidity('');
-    } else {
-      input.setCustomValidity('Hey, you\'re supposed to type \'shoelace\' before submitting this!');
-    }
-  });
-</script>
-```
-
-```jsx react
-import { useRef, useState } from 'react';
-import { 
-  SlButton,
-  SlForm, 
-  SlInput
-} from '@shoelace-style/shoelace/dist/react';
-
-const App = () => {
-  const input = useRef(null);
-  const [value, setValue] = useState('');
-
-  function handleInput(event) {
-    setValue(event.target.value);
-
-    if (event.target.value === 'shoelace') {
-      input.current.setCustomValidity('');
-    } else {
-      input.current.setCustomValidity('Hey, you\'re supposed to type \'shoelace\' before submitting this!');
-    }
-  }
-
-  return (
-    <SlForm onSlSubmit={() => alert('All fields are valid!')}>
-      <SlInput 
-        ref={input}
-        label="Type 'shoelace'" 
-        required 
-        value={value} 
-        onSlInput={handleInput}
-      />
-      <br />
-      <SlButton variant="primary" submit>Submit</SlButton>
-    </SlForm>
-  );
-};
-```
-
-### Custom Validation Styles
-
-The `invalid` attribute reflects the form control's validity, so you can style invalid fields using the `[invalid]` selector. The example below demonstrates how you can give erroneous fields a different appearance. Type something other than "shoelace" to demonstrate this.
-
-```html preview
-<sl-input class="custom-input" required pattern="shoelace">
-  <small slot="help-text">Please enter "shoelace" to continue</small>
-</sl-input>
-
-<style>
-  .custom-input[invalid]:not([disabled])::part(label),
-  .custom-input[invalid]:not([disabled])::part(help-text) {
-    color: var(--sl-color-danger-600);
-  }
-
-  .custom-input[invalid]:not([disabled])::part(base) {      
-    border-color: var(--sl-color-danger-500);
-  } 
-
-  .custom-input[invalid]:focus-within::part(base) {
-    box-shadow: 0 0 0 var(--sl-focus-ring-width) var(--sl-color-danger-500);
-  }
-</style>
-```
-
-```jsx react
-import { SlInput } from '@shoelace-style/shoelace/dist/react';
-
-const css = `
-  .custom-input[invalid]:not([disabled])::part(label),
-  .custom-input[invalid]:not([disabled])::part(help-text) {
-    color: var(--sl-color-danger-600);
-  }
-
-  .custom-input[invalid]:not([disabled])::part(base) {      
-    border-color: var(--sl-color-danger-500);
-  } 
-
-  .custom-input[invalid]:focus-within::part(base) {
-    box-shadow: 0 0 0 var(--sl-focus-ring-width) var(--sl-color-danger-500);
-  }
-`;
-
-const App = () => (
-  <>
-    <SlInput className="custom-input" required pattern="shoelace">
-      <small slot="help-text">Please enter "shoelace" to continue</small>
-    </SlInput>
-
-    <style>{css}</style>
-  </>
-);
-```
-
-### Third-party Validation
-
-To opt out of the browser's built-in validation and use your own, add the `novalidate` attribute to the form. This will ignore all constraints and prevent the browser from showing its own warnings when form controls are invalid.
-
-Remember that the `invalid` attribute on form controls reflects validity as defined by the [Constraint Validation API](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation). You can set it initially, but the `invalid` attribute will update as the user interacts with the form control. As such, you should not rely on it to set invalid styles using a custom validation library.
-
-Instead, toggle a class and target it in your stylesheet as shown below.
-
-```html
-<sl-form novalidate>
-  <sl-input class="invalid"></sl-input>
-</sl-form>
-
-<style>
-  sl-input.invalid {
-    ...
-  }
-</style>
-```
-
-[component-metadata:sl-form]

docs/components/format-bytes.md

@@ -2,13 +2,10 @@
 
 [component-header:sl-format-bytes]
 
-Formats a number as a human readable bytes value.
-
 ```html preview
 <div class="format-bytes-overview">
-  The file is <sl-format-bytes value="1000"></sl-format-bytes> in size.
-  <br><br>
-  <sl-input type="number" value="1000" label="Number to Format" style="max-width: 180px;"></sl-input>  
+  The file is <sl-format-bytes value="1000"></sl-format-bytes> in size. <br /><br />
+  <sl-input type="number" value="1000" label="Number to Format" style="max-width: 180px;"></sl-input>
 </div>
 
 <script>
@@ -16,18 +13,13 @@ Formats a number as a human readable bytes value.
   const formatter = container.querySelector('sl-format-bytes');
   const input = container.querySelector('sl-input');
 
-  input.addEventListener('sl-input', () => formatter.value = input.value || 0);
+  input.addEventListener('sl-input', () => (formatter.value = input.value || 0));
 </script>
 ```
 
-
 ```jsx react
 import { useState } from 'react';
-import { 
-  SlButton, 
-  SlFormatBytes, 
-  SlInput 
-} from '@shoelace-style/shoelace/dist/react';
+import { SlButton, SlFormatBytes, SlInput } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [value, setValue] = useState(1000);
@@ -35,11 +27,12 @@ const App = () => {
   return (
     <>
       The file is <SlFormatBytes value={value} /> in size.
-      <br /><br />
-      <SlInput 
-        type="number" 
+      <br />
+      <br />
+      <SlInput
+        type="number"
         value={value}
-        label="Number to Format" 
+        label="Number to Format"
         style={{ maxWidth: '180px' }}
         onSlInput={event => setValue(event.target.value)}
       />
@@ -55,21 +48,23 @@ const App = () => {
 Set the `value` attribute to a number to get the value in bytes.
 
 ```html preview
-<sl-format-bytes value="12"></sl-format-bytes><br>
-<sl-format-bytes value="1200"></sl-format-bytes><br>
-<sl-format-bytes value="1200000"></sl-format-bytes><br>
+<sl-format-bytes value="12"></sl-format-bytes><br />
+<sl-format-bytes value="1200"></sl-format-bytes><br />
+<sl-format-bytes value="1200000"></sl-format-bytes><br />
 <sl-format-bytes value="1200000000"></sl-format-bytes>
 ```
 
-
 ```jsx react
 import { SlFormatBytes } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlFormatBytes value="12" /><br />
-    <SlFormatBytes value="1200" /><br />
-    <SlFormatBytes value="1200000" /><br />
+    <SlFormatBytes value="12" />
+    <br />
+    <SlFormatBytes value="1200" />
+    <br />
+    <SlFormatBytes value="1200000" />
+    <br />
     <SlFormatBytes value="1200000000" />
   </>
 );
@@ -77,13 +72,13 @@ const App = () => (
 
 ### Formatting Bits
 
-To get the value in bits, set the `unit` attribute to `bits`.
+To get the value in bits, set the `unit` attribute to `bit`.
 
 ```html preview
-<sl-format-bytes value="12" unit="bits"></sl-format-bytes><br>
-<sl-format-bytes value="1200" unit="bits"></sl-format-bytes><br>
-<sl-format-bytes value="1200000" unit="bits"></sl-format-bytes><br>
-<sl-format-bytes value="1200000000" unit="bits"></sl-format-bytes>
+<sl-format-bytes value="12" unit="bit"></sl-format-bytes><br />
+<sl-format-bytes value="1200" unit="bit"></sl-format-bytes><br />
+<sl-format-bytes value="1200000" unit="bit"></sl-format-bytes><br />
+<sl-format-bytes value="1200000000" unit="bit"></sl-format-bytes>
 ```
 
 ```jsx react
@@ -91,10 +86,13 @@ import { SlFormatBytes } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlFormatBytes value="12" unit="bits" /><br />
-    <SlFormatBytes value="1200" unit="bits" /><br />
-    <SlFormatBytes value="1200000" unit="bits" /><br />
-    <SlFormatBytes value="1200000000" unit="bits" />
+    <SlFormatBytes value="12" unit="bit" />
+    <br />
+    <SlFormatBytes value="1200" unit="bit" />
+    <br />
+    <SlFormatBytes value="1200000" unit="bit" />
+    <br />
+    <SlFormatBytes value="1200000000" unit="bit" />
   </>
 );
 ```
@@ -104,9 +102,9 @@ const App = () => (
 Use the `lang` attribute to set the number formatting locale.
 
 ```html preview
-<sl-format-bytes value="12" lang="de"></sl-format-bytes><br>
-<sl-format-bytes value="1200" lang="de"></sl-format-bytes><br>
-<sl-format-bytes value="1200000" lang="de"></sl-format-bytes><br>
+<sl-format-bytes value="12" lang="de"></sl-format-bytes><br />
+<sl-format-bytes value="1200" lang="de"></sl-format-bytes><br />
+<sl-format-bytes value="1200000" lang="de"></sl-format-bytes><br />
 <sl-format-bytes value="1200000000" lang="de"></sl-format-bytes>
 ```
 
@@ -115,9 +113,12 @@ import { SlFormatBytes } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlFormatBytes value="12" lang="de" /><br />
-    <SlFormatBytes value="1200" lang="de" /><br />
-    <SlFormatBytes value="1200000" lang="de" /><br />
+    <SlFormatBytes value="12" lang="de" />
+    <br />
+    <SlFormatBytes value="1200" lang="de" />
+    <br />
+    <SlFormatBytes value="1200000" lang="de" />
+    <br />
     <SlFormatBytes value="1200000000" lang="de" />
   </>
 );

docs/components/format-date.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-format-date]
 
-Formats a date/time using the specified locale and options.
-
 Localization is handled by the browser's [`Intl.DateTimeFormat` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat). No language packs are required.
 
 ```html preview
@@ -14,9 +12,7 @@ Localization is handled by the browser's [`Intl.DateTimeFormat` API](https://dev
 ```jsx react
 import { SlFormatDate } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlFormatDate date="2020-07-15T09:17:00-04:00" />
-);
+const App = () => <SlFormatDate date="2020-07-15T09:17:00-04:00" />;
 ```
 
 The `date` attribute determines the date/time to use when formatting. It must be a string that [`Date.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse) can interpret or a [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) object set via JavaScript. If omitted, the current date/time will be assumed.
@@ -31,19 +27,19 @@ Formatting options are based on those found in the [`Intl.DateTimeFormat` API](h
 
 ```html preview
 <!-- Human-readable date -->
-<sl-format-date month="long" day="numeric" year="numeric"></sl-format-date><br>
+<sl-format-date month="long" day="numeric" year="numeric"></sl-format-date><br />
 
 <!-- Time -->
-<sl-format-date hour="numeric" minute="numeric"></sl-format-date><br>
+<sl-format-date hour="numeric" minute="numeric"></sl-format-date><br />
 
 <!-- Weekday -->
-<sl-format-date weekday="long"></sl-format-date><br>
+<sl-format-date weekday="long"></sl-format-date><br />
 
 <!-- Month -->
-<sl-format-date month="long"></sl-format-date><br>
+<sl-format-date month="long"></sl-format-date><br />
 
 <!-- Year -->
-<sl-format-date year="numeric"></sl-format-date><br>
+<sl-format-date year="numeric"></sl-format-date><br />
 
 <!-- No formatting options -->
 <sl-format-date></sl-format-date>
@@ -55,19 +51,24 @@ import { SlFormatDate } from '@shoelace-style/shoelace/dist/react';
 const App = () => (
   <>
     {/* Human-readable date */}
-    <SlFormatDate month="long" day="numeric" year="numeric" /><br />
+    <SlFormatDate month="long" day="numeric" year="numeric" />
+    <br />
 
     {/* Time */}
-    <SlFormatDate hour="numeric" minute="numeric" /><br />
+    <SlFormatDate hour="numeric" minute="numeric" />
+    <br />
 
     {/* Weekday */}
-    <SlFormatDate weekday="long" /><br />
+    <SlFormatDate weekday="long" />
+    <br />
 
     {/* Month */}
-    <SlFormatDate month="long" /><br />
+    <SlFormatDate month="long" />
+    <br />
 
     {/* Year */}
-    <SlFormatDate year="numeric" /><br />
+    <SlFormatDate year="numeric" />
+    <br />
 
     {/* No formatting options */}
     <SlFormatDate />
@@ -80,7 +81,7 @@ const App = () => (
 By default, the browser will determine whether to use 12-hour or 24-hour time. To force one or the other, set the `hour-format` attribute to `12` or `24`.
 
 ```html preview
-<sl-format-date hour="numeric" minute="numeric" hour-format="12"></sl-format-date><br>
+<sl-format-date hour="numeric" minute="numeric" hour-format="12"></sl-format-date><br />
 <sl-format-date hour="numeric" minute="numeric" hour-format="24"></sl-format-date>
 ```
 
@@ -89,7 +90,8 @@ import { SlFormatDate } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlFormatDate hour="numeric" minute="numeric" hour-format="12" /><br />
+    <SlFormatDate hour="numeric" minute="numeric" hour-format="12" />
+    <br />
     <SlFormatDate hour="numeric" minute="numeric" hour-format="24" />
   </>
 );
@@ -100,8 +102,8 @@ const App = () => (
 Use the `lang` attribute to set the date/time formatting locale.
 
 ```html preview
-English: <sl-format-date lang="en"></sl-format-date><br>
-French: <sl-format-date lang="fr"></sl-format-date><br>
+English: <sl-format-date lang="en"></sl-format-date><br />
+French: <sl-format-date lang="fr"></sl-format-date><br />
 Russian: <sl-format-date lang="ru"></sl-format-date>
 ```
 
@@ -110,8 +112,10 @@ import { SlFormatDate } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    English: <SlFormatDate lang="en" /><br />
-    French: <SlFormatDate lang="fr" /><br />
+    English: <SlFormatDate lang="en" />
+    <br />
+    French: <SlFormatDate lang="fr" />
+    <br />
     Russian: <SlFormatDate lang="ru" />
   </>
 );

docs/components/format-number.md

@@ -2,15 +2,13 @@
 
 [component-header:sl-format-number]
 
-Formats a number using the specified locale and options.
-
 Localization is handled by the browser's [`Intl.NumberFormat` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat). No language packs are required.
 
 ```html preview
 <div class="format-number-overview">
-  <sl-format-number value="1000"></sl-format-number> 
-  <br><br>
-  <sl-input type="number" value="1000" label="Number to Format" style="max-width: 180px;"></sl-input>  
+  <sl-format-number value="1000"></sl-format-number>
+  <br /><br />
+  <sl-input type="number" value="1000" label="Number to Format" style="max-width: 180px;"></sl-input>
 </div>
 
 <script>
@@ -18,7 +16,7 @@ Localization is handled by the browser's [`Intl.NumberFormat` API](https://devel
   const formatter = container.querySelector('sl-format-number');
   const input = container.querySelector('sl-input');
 
-  input.addEventListener('sl-input', () => formatter.value = input.value || 0);
+  input.addEventListener('sl-input', () => (formatter.value = input.value || 0));
 </script>
 ```
 
@@ -32,11 +30,12 @@ const App = () => {
   return (
     <>
       <SlFormatNumber value={value} />
-      <br /><br />
-      <SlInput 
-        type="number" 
-        value={value} 
-        label="Number to Format" 
+      <br />
+      <br />
+      <SlInput
+        type="number"
+        value={value}
+        label="Number to Format"
         style={{ maxWidth: '180px' }}
         onSlInput={event => setValue(event.target.value)}
       />
@@ -52,10 +51,10 @@ const App = () => {
 To get the value as a percent, set the `type` attribute to `percent`.
 
 ```html preview
-<sl-format-number type="percent" value="0"></sl-format-number><br>
-<sl-format-number type="percent" value="0.25"></sl-format-number><br>
-<sl-format-number type="percent" value="0.50"></sl-format-number><br>
-<sl-format-number type="percent" value="0.75"></sl-format-number><br>
+<sl-format-number type="percent" value="0"></sl-format-number><br />
+<sl-format-number type="percent" value="0.25"></sl-format-number><br />
+<sl-format-number type="percent" value="0.50"></sl-format-number><br />
+<sl-format-number type="percent" value="0.75"></sl-format-number><br />
 <sl-format-number type="percent" value="1"></sl-format-number>
 ```
 
@@ -64,11 +63,15 @@ import { SlFormatNumber } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlFormatNumber type="percent" value={0} /><br />
-    <SlFormatNumber type="percent" value={0.25} /><br />
-    <SlFormatNumber type="percent" value={0.50} /><br />
-    <SlFormatNumber type="percent" value={0.75} /><br />
-    <SlFormatNumber type="percent" value={1} />  
+    <SlFormatNumber type="percent" value={0} />
+    <br />
+    <SlFormatNumber type="percent" value={0.25} />
+    <br />
+    <SlFormatNumber type="percent" value={0.5} />
+    <br />
+    <SlFormatNumber type="percent" value={0.75} />
+    <br />
+    <SlFormatNumber type="percent" value={1} />
   </>
 );
 ```
@@ -78,8 +81,8 @@ const App = () => (
 Use the `lang` attribute to set the number formatting locale.
 
 ```html preview
-English: <sl-format-number value="2000" lang="en" minimum-fraction-digits="2"></sl-format-number><br>
-German: <sl-format-number value="2000" lang="de" minimum-fraction-digits="2"></sl-format-number><br>
+English: <sl-format-number value="2000" lang="en" minimum-fraction-digits="2"></sl-format-number><br />
+German: <sl-format-number value="2000" lang="de" minimum-fraction-digits="2"></sl-format-number><br />
 Russian: <sl-format-number value="2000" lang="ru" minimum-fraction-digits="2"></sl-format-number>
 ```
 
@@ -88,8 +91,10 @@ import { SlFormatNumber } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    English: <SlFormatNumber value="2000" lang="en" minimum-fraction-digits="2" /><br />
-    German: <SlFormatNumber value="2000" lang="de" minimum-fraction-digits="2" /><br />
+    English: <SlFormatNumber value="2000" lang="en" minimum-fraction-digits="2" />
+    <br />
+    German: <SlFormatNumber value="2000" lang="de" minimum-fraction-digits="2" />
+    <br />
     Russian: <SlFormatNumber value="2000" lang="ru" minimum-fraction-digits="2" />
   </>
 );
@@ -100,10 +105,10 @@ const App = () => (
 To format a number as a monetary value, set the `type` attribute to `currency` and set the `currency` attribute to the desired ISO 4217 currency code. You should also specify `lang` to ensure the the number is formatted correctly for the target locale.
 
 ```html preview
-<sl-format-number type="currency" currency="USD" value="2000" lang="en-US"></sl-format-number><br>
-<sl-format-number type="currency" currency="GBP" value="2000" lang="en-GB"></sl-format-number><br>
-<sl-format-number type="currency" currency="EUR" value="2000" lang="de"></sl-format-number><br>
-<sl-format-number type="currency" currency="RUB" value="2000" lang="ru"></sl-format-number><br>
+<sl-format-number type="currency" currency="USD" value="2000" lang="en-US"></sl-format-number><br />
+<sl-format-number type="currency" currency="GBP" value="2000" lang="en-GB"></sl-format-number><br />
+<sl-format-number type="currency" currency="EUR" value="2000" lang="de"></sl-format-number><br />
+<sl-format-number type="currency" currency="RUB" value="2000" lang="ru"></sl-format-number><br />
 <sl-format-number type="currency" currency="CNY" value="2000" lang="zh-cn"></sl-format-number>
 ```
 
@@ -112,10 +117,14 @@ import { SlFormatNumber } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlFormatNumber type="currency" currency="USD" value="2000" lang="en-US" /><br />
-    <SlFormatNumber type="currency" currency="GBP" value="2000" lang="en-GB" /><br />
-    <SlFormatNumber type="currency" currency="EUR" value="2000" lang="de" /><br />
-    <SlFormatNumber type="currency" currency="RUB" value="2000" lang="ru" /><br />
+    <SlFormatNumber type="currency" currency="USD" value="2000" lang="en-US" />
+    <br />
+    <SlFormatNumber type="currency" currency="GBP" value="2000" lang="en-GB" />
+    <br />
+    <SlFormatNumber type="currency" currency="EUR" value="2000" lang="de" />
+    <br />
+    <SlFormatNumber type="currency" currency="RUB" value="2000" lang="ru" />
+    <br />
     <SlFormatNumber type="currency" currency="CNY" value="2000" lang="zh-cn" />
   </>
 );

docs/components/icon-button.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-icon-button]
 
-Icons buttons are simple, icon-only buttons that can be used for actions and in toolbars.
-
 For a full list of icons that come bundled with Shoelace, refer to the [icon component](/components/icon).
 
 ```html preview
@@ -13,9 +11,7 @@ For a full list of icons that come bundled with Shoelace, refer to the [icon com
 ```jsx react
 import { SlIconButton } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlIconButton name="gear" label="Settings" />
-);
+const App = () => <SlIconButton name="gear" label="Settings" />;
 ```
 
 ## Examples
@@ -111,14 +107,7 @@ Use the `href` attribute to convert the button to a link.
 ```jsx react
 import { SlIconButton } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlIconButton 
-    name="gear" 
-    label="Settings" 
-    href="https://example.com" 
-    target="_blank"
-  />
-);
+const App = () => <SlIconButton name="gear" label="Settings" href="https://example.com" target="_blank" />;
 ```
 
 ### Icon Button with Tooltip
@@ -152,9 +141,7 @@ Use the `disabled` attribute to disable the icon button.
 ```jsx react
 import { SlIconButton } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlIconButton name="gear" label="Settings" disabled />
-);
+const App = () => <SlIconButton name="gear" label="Settings" disabled />;
 ```
 
 [component-metadata:sl-icon-button]

docs/components/icon.md

@@ -2,11 +2,13 @@
 
 [component-header:sl-icon]
 
-Icons are symbols that can be used to represent various options within an application.
-
 Shoelace comes bundled with over 1,500 icons courtesy of the [Bootstrap Icons](https://icons.getbootstrap.com/) project. These icons are part of the `default` icon library. If you prefer, you can register [custom icon libraries](#icon-libraries) as well.
 
-Click or tap on an icon below to copy its name and use it like this.
+?> Depending on how you're loading Shoelace, you may need to copy icon assets and/or [set the base path](getting-started/installation#setting-the-base-path) so Shoelace knows where to load them from. Otherwise, icons may not appear and you'll see 404 Not Found errors in the dev console.
+
+## Default Icons
+
+All available icons in the `default` icon library are shown below. Click or tap on any icon to copy its name, then you can use it in your HTML like this.
 
 ```html
 <sl-icon name="icon-name-here"></sl-icon>
@@ -18,17 +20,81 @@ Click or tap on an icon below to copy its name and use it like this.
       <sl-icon slot="prefix" name="search"></sl-icon>
     </sl-input>
     <sl-select value="outline">
-      <sl-menu-item value="outline">Outlined</sl-menu-item>
-      <sl-menu-item value="fill">Filled</sl-menu-item>
-      <sl-menu-item value="all">All icons</sl-menu-item>
+      <sl-option value="outline">Outlined</sl-option>
+      <sl-option value="fill">Filled</sl-option>
+      <sl-option value="all">All icons</sl-option>
     </sl-select>
   </div>
   <div class="icon-list"></div>
-  <input type="text" class="icon-copy-input">
+  <input type="text" class="icon-copy-input" aria-hidden="true" tabindex="-1">
 </div>
 
 ## Examples
 
+### Colors
+
+Icons inherit their color from the current text color. Thus, you can set the `color` property on the `<sl-icon>` element or an ancestor to change the color.
+
+```html preview
+<div style="color: #4a90e2;">
+  <sl-icon name="exclamation-triangle"></sl-icon>
+  <sl-icon name="archive"></sl-icon>
+  <sl-icon name="battery-charging"></sl-icon>
+  <sl-icon name="bell"></sl-icon>
+</div>
+<div style="color: #9013fe;">
+  <sl-icon name="clock"></sl-icon>
+  <sl-icon name="cloud"></sl-icon>
+  <sl-icon name="download"></sl-icon>
+  <sl-icon name="file-earmark"></sl-icon>
+</div>
+<div style="color: #417505;">
+  <sl-icon name="flag"></sl-icon>
+  <sl-icon name="heart"></sl-icon>
+  <sl-icon name="image"></sl-icon>
+  <sl-icon name="lightning"></sl-icon>
+</div>
+<div style="color: #f5a623;">
+  <sl-icon name="mic"></sl-icon>
+  <sl-icon name="search"></sl-icon>
+  <sl-icon name="star"></sl-icon>
+  <sl-icon name="trash"></sl-icon>
+</div>
+```
+
+```jsx react
+import { SlIcon } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <div style={{ color: '#4a90e2' }}>
+      <SlIcon name="exclamation-triangle"></SlIcon>
+      <SlIcon name="archive"></SlIcon>
+      <SlIcon name="battery-charging"></SlIcon>
+      <SlIcon name="bell"></SlIcon>
+    </div>
+    <div style={{ color: '#9013fe' }}>
+      <SlIcon name="clock"></SlIcon>
+      <SlIcon name="cloud"></SlIcon>
+      <SlIcon name="download"></SlIcon>
+      <SlIcon name="file-earmark"></SlIcon>
+    </div>
+    <div style={{ color: '#417505' }}>
+      <SlIcon name="flag"></SlIcon>
+      <SlIcon name="heart"></SlIcon>
+      <SlIcon name="image"></SlIcon>
+      <SlIcon name="lightning"></SlIcon>
+    </div>
+    <div style={{ color: '#f5a623' }}>
+      <SlIcon name="mic"></SlIcon>
+      <SlIcon name="search"></SlIcon>
+      <SlIcon name="star"></SlIcon>
+      <SlIcon name="trash"></SlIcon>
+    </div>
+  </>
+);
+```
+
 ### Sizing
 
 Icons are sized relative to the current font size. To change their size, set the `font-size` property on the icon itself or on a parent element as shown below.
@@ -75,7 +141,7 @@ const App = () => (
     <SlIcon name="search" />
     <SlIcon name="star" />
     <SlIcon name="trash" />
-  </div>  
+  </div>
 );
 ```
 
@@ -90,9 +156,7 @@ For non-decorative icons, use the `label` attribute to announce it to assistive
 ```jsx react
 import { SlIcon } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlIcon name="star-fill" label="Add to favorites" />
-);
+const App = () => <SlIcon name="star-fill" label="Add to favorites" />;
 ```
 
 ### Custom Icons
@@ -103,13 +167,10 @@ Custom icons can be loaded individually with the `src` attribute. Only SVGs on a
 <sl-icon src="https://shoelace.style/assets/images/shoe.svg" style="font-size: 8rem;"></sl-icon>
 ```
 
-
 ```jsx react
 import { SlIcon } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlIcon src="https://shoelace.style/assets/images/shoe.svg" style={{ fontSize: '8rem' }}></SlIcon>
-);
+const App = () => <SlIcon src="https://shoelace.style/assets/images/shoe.svg" style={{ fontSize: '8rem' }}></SlIcon>;
 ```
 
 ## Icon Libraries
@@ -163,7 +224,7 @@ Icons in this library are licensed under the [Creative Commons 4.0 License](http
       if (name.substring(0, 4) === 'bxl-') folder = 'logos';
       return `https://cdn.jsdelivr.net/npm/boxicons@2.0.5/svg/${folder}/${name}.svg`;
     },
-    mutator:svg => svg.setAttribute('fill', 'currentColor')
+    mutator: svg => svg.setAttribute('fill', 'currentColor')
   });
 </script>
 
@@ -174,14 +235,14 @@ Icons in this library are licensed under the [Creative Commons 4.0 License](http
   <sl-icon library="boxicons" name="bx-save"></sl-icon>
   <sl-icon library="boxicons" name="bx-server"></sl-icon>
   <sl-icon library="boxicons" name="bx-wine"></sl-icon>
-  <br>
+  <br />
   <sl-icon library="boxicons" name="bxs-bot"></sl-icon>
   <sl-icon library="boxicons" name="bxs-cookie"></sl-icon>
   <sl-icon library="boxicons" name="bxs-joystick"></sl-icon>
   <sl-icon library="boxicons" name="bxs-save"></sl-icon>
   <sl-icon library="boxicons" name="bxs-server"></sl-icon>
   <sl-icon library="boxicons" name="bxs-wine"></sl-icon>
-  <br>
+  <br />
   <sl-icon library="boxicons" name="bxl-apple"></sl-icon>
   <sl-icon library="boxicons" name="bxl-chrome"></sl-icon>
   <sl-icon library="boxicons" name="bxl-edge"></sl-icon>
@@ -191,27 +252,27 @@ Icons in this library are licensed under the [Creative Commons 4.0 License](http
 </div>
 ```
 
-### Feather Icons
+### Lucide
 
-This will register the [Feather Icons](https://feathericons.com/) library using the jsDelivr CDN.
+This will register the [Lucide](https://lucide.dev/) icon library using the jsDelivr CDN. This project is a community-maintained fork of the popular [Feather](https://feathericons.com/) icon library.
 
-Icons in this library are licensed under the [MIT License](https://github.com/feathericons/feather/blob/master/LICENSE).
+Icons in this library are licensed under the [MIT License](https://github.com/lucide-icons/lucide/blob/master/LICENSE).
 
 ```html preview
 <div style="font-size: 24px;">
-  <sl-icon library="feather" name="feather"></sl-icon>
-  <sl-icon library="feather" name="pie-chart"></sl-icon>
-  <sl-icon library="feather" name="settings"></sl-icon>
-  <sl-icon library="feather" name="map-pin"></sl-icon>
-  <sl-icon library="feather" name="printer"></sl-icon>
-  <sl-icon library="feather" name="shopping-cart"></sl-icon>
+  <sl-icon library="lucide" name="feather"></sl-icon>
+  <sl-icon library="lucide" name="pie-chart"></sl-icon>
+  <sl-icon library="lucide" name="settings"></sl-icon>
+  <sl-icon library="lucide" name="map-pin"></sl-icon>
+  <sl-icon library="lucide" name="printer"></sl-icon>
+  <sl-icon library="lucide" name="shopping-cart"></sl-icon>
 </div>
 
 <script type="module">
   import { registerIconLibrary } from '/dist/utilities/icon-library.js';
 
-  registerIconLibrary('feather', {
-    resolver: name => `https://cdn.jsdelivr.net/npm/feather-icons@4.28.0/dist/icons/${name}.svg`
+  registerIconLibrary('lucide', {
+    resolver: name => `https://cdn.jsdelivr.net/npm/lucide-static@0.16.29/icons/${name}.svg`
   });
 </script>
 ```
@@ -245,20 +306,20 @@ Icons in this library are licensed under the [Font Awesome Free License](https:/
   <sl-icon library="fa" name="far-hdd"></sl-icon>
   <sl-icon library="fa" name="far-heart"></sl-icon>
   <sl-icon library="fa" name="far-star"></sl-icon>
-  <br>
+  <br />
   <sl-icon library="fa" name="fas-archive"></sl-icon>
   <sl-icon library="fa" name="fas-book"></sl-icon>
   <sl-icon library="fa" name="fas-chess-knight"></sl-icon>
   <sl-icon library="fa" name="fas-dice"></sl-icon>
   <sl-icon library="fa" name="fas-pizza-slice"></sl-icon>
   <sl-icon library="fa" name="fas-scroll"></sl-icon>
-  <br>
+  <br />
   <sl-icon library="fa" name="fab-apple"></sl-icon>
   <sl-icon library="fa" name="fab-chrome"></sl-icon>
   <sl-icon library="fa" name="fab-edge"></sl-icon>
   <sl-icon library="fa" name="fab-firefox"></sl-icon>
   <sl-icon library="fa" name="fab-opera"></sl-icon>
-  <sl-icon library="fa" name="fab-microsoft"></sl-icon>    
+  <sl-icon library="fa" name="fab-microsoft"></sl-icon>
 </div>
 ```
 
@@ -273,17 +334,17 @@ Icons in this library are licensed under the [MIT License](https://github.com/ta
   import { registerIconLibrary } from '/dist/utilities/icon-library.js';
 
   registerIconLibrary('heroicons', {
-    resolver: name => `https://cdn.jsdelivr.net/npm/heroicons@0.4.2/outline/${name}.svg`
+    resolver: name => `https://cdn.jsdelivr.net/npm/heroicons@2.0.1/24/outline/${name}.svg`
   });
 </script>
 
 <div style="font-size: 24px;">
-  <sl-icon library="heroicons" name="chat"></sl-icon>
+  <sl-icon library="heroicons" name="chat-bubble-left"></sl-icon>
   <sl-icon library="heroicons" name="cloud"></sl-icon>
   <sl-icon library="heroicons" name="cog"></sl-icon>
   <sl-icon library="heroicons" name="document-text"></sl-icon>
   <sl-icon library="heroicons" name="gift"></sl-icon>
-  <sl-icon library="heroicons" name="volume-up"></sl-icon>
+  <sl-icon library="heroicons" name="speaker-wave"></sl-icon>
 </div>
 ```
 
@@ -340,14 +401,14 @@ Icons in this library are licensed under the [MIT License](https://github.com/io
   <sl-icon library="ionicons" name="chatbubble"></sl-icon>
   <sl-icon library="ionicons" name="settings"></sl-icon>
   <sl-icon library="ionicons" name="warning"></sl-icon>
-  <br>
+  <br />
   <sl-icon library="ionicons" name="alarm-outline"></sl-icon>
   <sl-icon library="ionicons" name="american-football-outline"></sl-icon>
   <sl-icon library="ionicons" name="bug-outline"></sl-icon>
   <sl-icon library="ionicons" name="chatbubble-outline"></sl-icon>
   <sl-icon library="ionicons" name="settings-outline"></sl-icon>
   <sl-icon library="ionicons" name="warning-outline"></sl-icon>
-  <br>
+  <br />
   <sl-icon library="ionicons" name="alarm-sharp"></sl-icon>
   <sl-icon library="ionicons" name="american-football-sharp"></sl-icon>
   <sl-icon library="ionicons" name="bug-sharp"></sl-icon>
@@ -380,7 +441,7 @@ Icons in this library are licensed under the [MIT License](https://github.com/mi
   <sl-icon library="jam" name="leaf"></sl-icon>
   <sl-icon library="jam" name="picture"></sl-icon>
   <sl-icon library="jam" name="set-square"></sl-icon>
-  <br>
+  <br />
   <sl-icon library="jam" name="calendar-f"></sl-icon>
   <sl-icon library="jam" name="camera-f"></sl-icon>
   <sl-icon library="jam" name="filter-f"></sl-icon>
@@ -416,14 +477,14 @@ Icons in this library are licensed under the [Apache 2.0 License](https://github
   <sl-icon library="material" name="volume_up"></sl-icon>
   <sl-icon library="material" name="settings"></sl-icon>
   <sl-icon library="material" name="shopping_basket"></sl-icon>
-  <br>
+  <br />
   <sl-icon library="material" name="notifications_round"></sl-icon>
   <sl-icon library="material" name="email_round"></sl-icon>
   <sl-icon library="material" name="delete_round"></sl-icon>
   <sl-icon library="material" name="volume_up_round"></sl-icon>
   <sl-icon library="material" name="settings_round"></sl-icon>
   <sl-icon library="material" name="shopping_basket_round"></sl-icon>
-  <br>
+  <br />
   <sl-icon library="material" name="notifications_sharp"></sl-icon>
   <sl-icon library="material" name="email_sharp"></sl-icon>
   <sl-icon library="material" name="delete_sharp"></sl-icon>
@@ -460,13 +521,45 @@ Icons in this library are licensed under the [Apache 2.0 License](https://github
   <sl-icon library="remixicon" name="development/bug-line"></sl-icon>
   <sl-icon library="remixicon" name="media/image-line"></sl-icon>
   <sl-icon library="remixicon" name="system/alert-line"></sl-icon>
-  <br>
+  <br />
   <sl-icon library="remixicon" name="business/cloud-fill"></sl-icon>
   <sl-icon library="remixicon" name="design/brush-fill"></sl-icon>
   <sl-icon library="remixicon" name="business/pie-chart-fill"></sl-icon>
   <sl-icon library="remixicon" name="development/bug-fill"></sl-icon>
   <sl-icon library="remixicon" name="media/image-fill"></sl-icon>
-  <sl-icon library="remixicon" name="system/alert-fill"></sl-icon>  
+  <sl-icon library="remixicon" name="system/alert-fill"></sl-icon>
+</div>
+```
+
+### Tabler Icons
+
+This will register the [Tabler Icons](https://tabler-icons.io/) library using the jsDelivr CDN. This library features over 1,950 open source icons.
+
+Icons in this library are licensed under the [MIT License](https://github.com/tabler/tabler-icons/blob/master/LICENSE).
+
+```html preview
+<script type="module">
+  import { registerIconLibrary } from '/dist/utilities/icon-library.js';
+
+  registerIconLibrary('tabler', {
+    resolver: name => `https://cdn.jsdelivr.net/npm/@tabler/icons@1.68.0/icons/${name}.svg`
+  });
+</script>
+
+<div style="font-size: 24px;">
+  <sl-icon library="tabler" name="alert-triangle"></sl-icon>
+  <sl-icon library="tabler" name="arrow-back"></sl-icon>
+  <sl-icon library="tabler" name="at"></sl-icon>
+  <sl-icon library="tabler" name="ball-baseball"></sl-icon>
+  <sl-icon library="tabler" name="cake"></sl-icon>
+  <sl-icon library="tabler" name="files"></sl-icon>
+  <br />
+  <sl-icon library="tabler" name="keyboard"></sl-icon>
+  <sl-icon library="tabler" name="moon"></sl-icon>
+  <sl-icon library="tabler" name="pig"></sl-icon>
+  <sl-icon library="tabler" name="printer"></sl-icon>
+  <sl-icon library="tabler" name="ship"></sl-icon>
+  <sl-icon library="tabler" name="toilet-paper"></sl-icon>
 </div>
 ```
 
@@ -483,7 +576,9 @@ Icons in this library are licensed under the [Apache 2.0 License](https://github
   registerIconLibrary('unicons', {
     resolver: name => {
       const match = name.match(/^(.*?)(-s)?$/);
-      return `https://cdn.jsdelivr.net/npm/@iconscout/unicons@3.0.3/svg/${match[2] === '-s' ? 'solid' : 'line'}/${match[1]}.svg`;
+      return `https://cdn.jsdelivr.net/npm/@iconscout/unicons@3.0.3/svg/${match[2] === '-s' ? 'solid' : 'line'}/${
+        match[1]
+      }.svg`;
     },
     mutator: svg => svg.setAttribute('fill', 'currentColor')
   });
@@ -496,12 +591,12 @@ Icons in this library are licensed under the [Apache 2.0 License](https://github
   <sl-icon library="unicons" name="polygon"></sl-icon>
   <sl-icon library="unicons" name="rocket"></sl-icon>
   <sl-icon library="unicons" name="star"></sl-icon>
-  <br>
+  <br />
   <sl-icon library="unicons" name="clock-s"></sl-icon>
   <sl-icon library="unicons" name="graph-bar-s"></sl-icon>
   <sl-icon library="unicons" name="padlock-s"></sl-icon>
   <sl-icon library="unicons" name="polygon-s"></sl-icon>
-  <sl-icon library="unicons" name="rocket-s"></sl-icon>  
+  <sl-icon library="unicons" name="rocket-s"></sl-icon>
   <sl-icon library="unicons" name="star-s"></sl-icon>
 </div>
 ```
@@ -540,6 +635,19 @@ If you want to change the icons Shoelace uses internally, you can register an ic
 
 <!-- Supporting scripts and styles for the search utility -->
 <script>
+  function wrapWithTooltip(item) {
+    const tooltip = document.createElement('sl-tooltip');
+    tooltip.content = item.getAttribute('data-name');
+
+    // Close open tooltips
+    document.querySelectorAll('.icon-list sl-tooltip[open]').forEach(tooltip => tooltip.hide());
+
+    // Wrap it with a tooltip and trick it into showing up
+    item.parentNode.insertBefore(tooltip, item);
+    tooltip.appendChild(item);
+    requestAnimationFrame(() => tooltip.dispatchEvent(new MouseEvent('mouseover')));
+  }
+
   fetch('/dist/assets/icons/icons.json')
     .then(res => res.json())  
     .then(icons => {
@@ -563,19 +671,23 @@ If you want to change the icons Shoelace uses internally, you can register an ic
             <use xlink:href="/assets/icons/sprite.svg#${i.name}"></use>
           </svg>      
         `;
+        list.appendChild(item);
 
-        const tooltip = document.createElement('sl-tooltip');
-        tooltip.content = i.name;
-        
-        tooltip.appendChild(item);
-        list.appendChild(tooltip);
+        // Wrap it with a tooltip the first time the mouse lands on it. We do this instead of baking them into the DOM 
+        // to improve this page's performance. See: https://github.com/shoelace-style/shoelace/issues/1122
+        item.addEventListener('mouseover', () => wrapWithTooltip(item), { once: true });
 
+        // Copy on click
         item.addEventListener('click', () => {
+          const tooltip = item.closest('sl-tooltip');
           copyInput.value = i.name;
           copyInput.select();
           document.execCommand('copy');
-          tooltip.content = 'Copied!';
-          setTimeout(() => tooltip.content = i.name, 1000);
+
+          if (tooltip) {
+            tooltip.content = 'Copied!';
+            setTimeout(() => tooltip.content = i.name, 1000);
+          }
         });
       });
 

docs/components/image-comparer.md

@@ -2,14 +2,20 @@
 
 [component-header:sl-image-comparer]
 
-Compare visual differences between similar photos with a sliding panel.
-
 For best results, use images that share the same dimensions. The slider can be controlled by dragging or pressing the left and right arrow keys. (Tip: press shift + arrows to move the slider in larger intervals, or home + end to jump to the beginning or end.)
 
 ```html preview
 <sl-image-comparer>
-  <img slot="before" src="https://images.unsplash.com/photo-1517331156700-3c241d2b4d83?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=800&q=80&sat=-100&bri=-5" alt="Grayscale version of kittens in a basket looking around.">
-  <img slot="after" src="https://images.unsplash.com/photo-1517331156700-3c241d2b4d83?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=800&q=80" alt="Color version of kittens in a basket looking around.">
+  <img
+    slot="before"
+    src="https://images.unsplash.com/photo-1517331156700-3c241d2b4d83?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=800&q=80&sat=-100&bri=-5"
+    alt="Grayscale version of kittens in a basket looking around."
+  />
+  <img
+    slot="after"
+    src="https://images.unsplash.com/photo-1517331156700-3c241d2b4d83?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=800&q=80"
+    alt="Color version of kittens in a basket looking around."
+  />
 </sl-image-comparer>
 ```
 
@@ -18,8 +24,16 @@ import { SlImageComparer } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlImageComparer>
-    <img slot="before" src="https://images.unsplash.com/photo-1517331156700-3c241d2b4d83?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=800&q=80&sat=-100&bri=-5" alt="Grayscale version of kittens in a basket looking around." />
-    <img slot="after" src="https://images.unsplash.com/photo-1517331156700-3c241d2b4d83?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=800&q=80" alt="Color version of kittens in a basket looking around." />
+    <img
+      slot="before"
+      src="https://images.unsplash.com/photo-1517331156700-3c241d2b4d83?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=800&q=80&sat=-100&bri=-5"
+      alt="Grayscale version of kittens in a basket looking around."
+    />
+    <img
+      slot="after"
+      src="https://images.unsplash.com/photo-1517331156700-3c241d2b4d83?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=800&q=80"
+      alt="Color version of kittens in a basket looking around."
+    />
   </SlImageComparer>
 );
 ```
@@ -32,8 +46,16 @@ Use the `position` attribute to set the initial position of the slider. This is
 
 ```html preview
 <sl-image-comparer position="25">
-  <img slot="before" src="https://images.unsplash.com/photo-1520903074185-8eca362b3dce?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1200&q=80" alt="A person sitting on bricks wearing untied boots.">
-  <img slot="after" src="https://images.unsplash.com/photo-1520640023173-50a135e35804?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=2250&q=80" alt="A person sitting on a yellow curb tying shoelaces on a boot.">
+  <img
+    slot="before"
+    src="https://images.unsplash.com/photo-1520903074185-8eca362b3dce?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1200&q=80"
+    alt="A person sitting on bricks wearing untied boots."
+  />
+  <img
+    slot="after"
+    src="https://images.unsplash.com/photo-1520640023173-50a135e35804?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=2250&q=80"
+    alt="A person sitting on a yellow curb tying shoelaces on a boot."
+  />
 </sl-image-comparer>
 ```
 
@@ -42,8 +64,16 @@ import { SlImageComparer } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlImageComparer position={25}>
-    <img slot="before" src="https://images.unsplash.com/photo-1520903074185-8eca362b3dce?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1200&q=80" alt="A person sitting on bricks wearing untied boots." />
-    <img slot="after" src="https://images.unsplash.com/photo-1520640023173-50a135e35804?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=2250&q=80" alt="A person sitting on a yellow curb tying shoelaces on a boot." />
+    <img
+      slot="before"
+      src="https://images.unsplash.com/photo-1520903074185-8eca362b3dce?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1200&q=80"
+      alt="A person sitting on bricks wearing untied boots."
+    />
+    <img
+      slot="after"
+      src="https://images.unsplash.com/photo-1520640023173-50a135e35804?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=2250&q=80"
+      alt="A person sitting on a yellow curb tying shoelaces on a boot."
+    />
   </SlImageComparer>
 );
 ```

docs/components/include.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-include]
 
-Includes give you the power to embed external HTML files into the page.
-
 Included files are asynchronously requested using `window.fetch()`. Requests are cached, so the same file can be included multiple times, but only one request will be made.
 
 The included content will be inserted into the `<sl-include>` element's default slot so it can be easily accessed and styled through the light DOM.
@@ -15,9 +13,7 @@ The included content will be inserted into the `<sl-include>` element's default
 ```jsx react
 import { SlInclude } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlInclude src="https://shoelace.style/assets/examples/include.html" />
-);
+const App = () => <SlInclude src="https://shoelace.style/assets/examples/include.html" />;
 ```
 
 ## Examples
@@ -33,13 +29,17 @@ If the request fails, the `sl-error` event will be emitted. In this case, `event
 
 <script>
   const include = document.querySelector('sl-include');
-  
-  include.addEventListener('sl-load', () => {
-    console.log('Success');
+
+  include.addEventListener('sl-load', event => {
+    if (event.eventPhase === Event.AT_TARGET) {
+      console.log('Success');
+    }
   });
 
   include.addEventListener('sl-error', event => {
-    console.log('Error', event.detail.status);
+    if (event.eventPhase === Event.AT_TARGET) {
+      console.log('Error', event.detail.status);
+    }
   });
 </script>
 ```

docs/components/input.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-input]
 
-Inputs collect data from the user.
-
 ```html preview
 <sl-input></sl-input>
 ```
@@ -11,17 +9,41 @@ Inputs collect data from the user.
 ```jsx react
 import { SlInput } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlInput />
-);
+const App = () => <SlInput />;
 ```
 
-?> This component doesn't work with standard forms. Use [`<sl-form>`](/components/form) instead.
-
-?> Please refer to the section on [form control validation](/components/form?id=form-control-validation) to learn how to do client-side validation.
+?> This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
 
 ## Examples
 
+### Labels
+
+Use the `label` attribute to give the input an accessible label. For labels that contain HTML, use the `label` slot instead.
+
+```html preview
+<sl-input label="What is your name?"></sl-input>
+```
+
+```jsx react
+import { SlIcon, SlInput } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => <SlInput label="What is your name?" />;
+```
+
+### Help Text
+
+Add descriptive help text to an input with the `help-text` attribute. For help texts that contain HTML, use the `help-text` slot instead.
+
+```html preview
+<sl-input label="Nickname" help-text="What would you like people to call you?"></sl-input>
+```
+
+```jsx react
+import { SlIcon, SlInput } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => <SlInput label="Nickname" help-text="What would you like people to call you?" />;
+```
+
 ### Placeholders
 
 Use the `placeholder` attribute to add a placeholder.
@@ -33,9 +55,7 @@ Use the `placeholder` attribute to add a placeholder.
 ```jsx react
 import { SlInput } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlInput placeholder="Type something" />
-);
+const App = () => <SlInput placeholder="Type something" />;
 ```
 
 ### Clearable
@@ -49,35 +69,21 @@ Add the `clearable` attribute to add a clear button when the input has content.
 ```jsx react
 import { SlInput } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlInput placeholder="Clearable" clearable />
-);
+const App = () => <SlInput placeholder="Clearable" clearable />;
 ```
 
 ### Toggle Password
 
-Add the `toggle-password` attribute to add a toggle button that will show the password when activated.
+Add the `password-toggle` attribute to add a toggle button that will show the password when activated.
 
 ```html preview
-<sl-input type="password" placeholder="Password Toggle" size="small" toggle-password></sl-input>
-<br>
-<sl-input type="password" placeholder="Password Toggle" size="medium" toggle-password></sl-input>
-<br>
-<sl-input type="password" placeholder="Password Toggle" size="large" toggle-password></sl-input>
+<sl-input type="password" placeholder="Password Toggle" password-toggle></sl-input>
 ```
 
 ```jsx react
 import { SlInput } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <>
-    <SlInput type="password" placeholder="Password Toggle" size="small" toggle-password />
-    <br />
-    <SlInput type="password" placeholder="Password Toggle" size="medium" toggle-password />
-    <br />
-    <SlInput type="password" placeholder="Password Toggle" size="large" toggle-password />  
-  </>
-);
+const App = () => <SlInput type="password" placeholder="Password Toggle" size="medium" password-toggle />;
 ```
 
 ### Filled Inputs
@@ -91,8 +97,46 @@ Add the `filled` attribute to draw a filled input.
 ```jsx react
 import { SlInput } from '@shoelace-style/shoelace/dist/react';
 
+const App = () => <SlInput placeholder="Type something" filled />;
+```
+
+### Disabled
+
+Use the `disabled` attribute to disable an input.
+
+```html preview
+<sl-input placeholder="Disabled" disabled></sl-input>
+```
+
+```jsx react
+import { SlInput } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => <SlInput placeholder="Disabled" disabled />;
+```
+
+### Sizes
+
+Use the `size` attribute to change an input's size.
+
+```html preview
+<sl-input placeholder="Small" size="small"></sl-input>
+<br />
+<sl-input placeholder="Medium" size="medium"></sl-input>
+<br />
+<sl-input placeholder="Large" size="large"></sl-input>
+```
+
+```jsx react
+import { SlInput } from '@shoelace-style/shoelace/dist/react';
+
 const App = () => (
-  <SlInput placeholder="Type something" filled />
+  <>
+    <SlInput placeholder="Small" size="small" />
+    <br />
+    <SlInput placeholder="Medium" size="medium" />
+    <br />
+    <SlInput placeholder="Large" size="large" />
+  </>
 );
 ```
 
@@ -102,9 +146,9 @@ Use the `pill` attribute to give inputs rounded edges.
 
 ```html preview
 <sl-input placeholder="Small" size="small" pill></sl-input>
-<br>
+<br />
 <sl-input placeholder="Medium" size="medium" pill></sl-input>
-<br>
+<br />
 <sl-input placeholder="Large" size="large" pill></sl-input>
 ```
 
@@ -127,11 +171,11 @@ const App = () => (
 The `type` attribute controls the type of input the browser renders.
 
 ```html preview
-<sl-input type="email" Placeholder="Email"></sl-input>
-<br>
-<sl-input type="number" Placeholder="Number"></sl-input>
-<br>
-<sl-input type="date" Placeholder="Date"></sl-input>
+<sl-input type="email" placeholder="Email"></sl-input>
+<br />
+<sl-input type="number" placeholder="Number"></sl-input>
+<br />
+<sl-input type="date" placeholder="Date"></sl-input>
 ```
 
 ```jsx react
@@ -139,63 +183,11 @@ import { SlInput } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlInput type="email" Placeholder="Email" />
+    <SlInput type="email" placeholder="Email" />
     <br />
-    <SlInput type="number" Placeholder="Number" />
+    <SlInput type="number" placeholder="Number" />
     <br />
-    <SlInput type="date" Placeholder="Date" />
-  </>
-);
-```
-
-### Disabled
-
-Use the `disabled` attribute to disable an input.
-
-```html preview
-<sl-input placeholder="Disabled" size="small" disabled></sl-input>
-<br>
-<sl-input placeholder="Disabled" size="medium" disabled></sl-input>
-<br>
-<sl-input placeholder="Disabled" size="large" disabled></sl-input>
-```
-
-```jsx react
-import { SlInput } from '@shoelace-style/shoelace/dist/react';
-
-const App = () => (
-  <>
-    <SlInput placeholder="Disabled" size="small" disabled />
-    <br />
-    <SlInput placeholder="Disabled" size="medium" disabled />
-    <br />
-    <SlInput placeholder="Disabled" size="large" disabled />
-  </>
-);
-```
-
-### Sizes
-
-Use the `size` attribute to change an input's size.
-
-```html preview
-<sl-input placeholder="Small" size="small"></sl-input>
-<br>
-<sl-input placeholder="Medium" size="medium"></sl-input>
-<br>
-<sl-input placeholder="Large" size="large"></sl-input>
-```
-
-```jsx react
-import { SlInput } from '@shoelace-style/shoelace/dist/react';
-
-const App = () => (
-  <>
-    <SlInput placeholder="Small" size="small" />
-    <br />
-    <SlInput placeholder="Medium" size="medium" />
-    <br />
-    <SlInput placeholder="Large" size="large" />
+    <SlInput type="date" placeholder="Date" />
   </>
 );
 ```
@@ -209,12 +201,12 @@ Use the `prefix` and `suffix` slots to add icons.
   <sl-icon name="house" slot="prefix"></sl-icon>
   <sl-icon name="chat" slot="suffix"></sl-icon>
 </sl-input>
-<br>
+<br />
 <sl-input placeholder="Medium" size="medium">
   <sl-icon name="house" slot="prefix"></sl-icon>
   <sl-icon name="chat" slot="suffix"></sl-icon>
 </sl-input>
-<br>
+<br />
 <sl-input placeholder="Large" size="large">
   <sl-icon name="house" slot="prefix"></sl-icon>
   <sl-icon name="chat" slot="suffix"></sl-icon>
@@ -244,42 +236,40 @@ const App = () => (
 );
 ```
 
-### Labels
+### Customizing Label Position
 
-Use the `label` attribute to give the input an accessible label. For labels that contain HTML, use the `label` slot instead.
+Use [CSS parts](#css-parts) to customize the way form controls are drawn. This example uses CSS grid to position the label to the left of the control, but the possible orientations are nearly endless. The same technique works for inputs, textareas, radio groups, and similar form controls.
 
 ```html preview
-<sl-input label="What is your name?"></sl-input>
-```
+<sl-input class="label-on-left" label="Name" help-text="Enter your name""></sl-input>
+<sl-input class="label-on-left" label="Email" type="email" help-text="Enter your email"></sl-input>
+<sl-textarea class="label-on-left" label="Bio" help-text="Tell us something about yourself"></sl-textarea>
 
-```jsx react
-import { SlIcon, SlInput } from '@shoelace-style/shoelace/dist/react';
+<style>
+  .label-on-left {
+    --label-width: 3.75rem;
+    --gap-width: 1rem;
+  }
 
-const App = () => (
-  <SlInput label="What is your name?" />
-);
-```
+  .label-on-left + .label-on-left {
+    margin-top: var(--sl-spacing-medium);
+  }
 
-### Help Text
+  .label-on-left::part(form-control) {
+    display: grid;
+    grid: auto / var(--label-width) 1fr;
+    gap: var(--sl-spacing-3x-small) var(--gap-width);
+    align-items: center;
+  }
 
-Add descriptive help text to an input with the `help-text` attribute. For help texts that contain HTML, use the `help-text` slot instead.
+  .label-on-left::part(form-control-label) {
+    text-align: right;
+  }
 
-```html preview
-<sl-input 
-  label="Nickname" 
-  help-text="What would you like people to call you?"
-></sl-input>
-```
-
-```jsx react
-import { SlIcon, SlInput } from '@shoelace-style/shoelace/dist/react';
-
-const App = () => (
-  <SlInput 
-    label="Nickname" 
-    help-text="What would you like people to call you?" 
-  />
-);
+  .label-on-left::part(form-control-help-text) {
+    grid-column-start: 2;
+  }
+</style>
 ```
 
 [component-metadata:sl-input]

docs/components/menu-item.md

@@ -2,15 +2,13 @@
 
 [component-header:sl-menu-item]
 
-Menu items provide options for the user to pick from in a menu.
-
 ```html preview
-<sl-menu style="max-width: 200px; border: solid 1px var(--sl-panel-border-color); background: var(--sl-panel-background-color); border-radius: var(--sl-border-radius-medium);">
+<sl-menu style="max-width: 200px;">
   <sl-menu-item>Option 1</sl-menu-item>
   <sl-menu-item>Option 2</sl-menu-item>
   <sl-menu-item>Option 3</sl-menu-item>
   <sl-divider></sl-divider>
-  <sl-menu-item checked>Checked</sl-menu-item>
+  <sl-menu-item type="checkbox" checked>Checkbox</sl-menu-item>
   <sl-menu-item disabled>Disabled</sl-menu-item>
   <sl-divider></sl-divider>
   <sl-menu-item>
@@ -25,26 +23,17 @@ Menu items provide options for the user to pick from in a menu.
 ```
 
 ```jsx react
-import { 
-  SlDivider,
-  SlIcon,
-  SlMenu,
-  SlMenuItem
-} from '@shoelace-style/shoelace/dist/react';
+import { SlDivider, SlIcon, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlMenu 
-    style={{
-      maxWidth: '200px',
-      border: 'solid 1px var(--sl-panel-border-color)',
-      borderRadius: 'var(--sl-border-radius-medium)'
-    }}
-  >
+  <SlMenu style={{ maxWidth: '200px' }}>
     <SlMenuItem>Option 1</SlMenuItem>
     <SlMenuItem>Option 2</SlMenuItem>
     <SlMenuItem>Option 3</SlMenuItem>
     <SlDivider />
-    <SlMenuItem checked>Checked</SlMenuItem>
+    <SlMenuItem type="checkbox" checked>
+      Checkbox
+    </SlMenuItem>
     <SlMenuItem disabled>Disabled</SlMenuItem>
     <SlDivider />
     <SlMenuItem>
@@ -55,51 +44,18 @@ const App = () => (
       Suffix Icon
       <SlIcon slot="suffix" name="heart" />
     </SlMenuItem>
-  </SlMenu>  
+  </SlMenu>
 );
 ```
 
 ## Examples
 
-### Checked
-
-Use the `checked` attribute to draw menu items in a checked state.
-
-```html preview
-<sl-menu style="max-width: 200px; border: solid 1px var(--sl-panel-border-color); background: var(--sl-panel-background-color); border-radius: var(--sl-border-radius-medium);">
-  <sl-menu-item>Option 1</sl-menu-item>
-  <sl-menu-item checked>Option 2</sl-menu-item>
-  <sl-menu-item>Option 3</sl-menu-item>
-</sl-menu>
-```
-
-```jsx react
-import { 
-  SlMenu,
-  SlMenuItem
-} from '@shoelace-style/shoelace/dist/react';
-
-const App = () => (
-  <SlMenu 
-    style={{
-      maxWidth: '200px',
-      border: 'solid 1px var(--sl-panel-border-color)',
-      borderRadius: 'var(--sl-border-radius-medium)'
-    }}
-  >
-    <SlMenuItem>Option 1</SlMenuItem>
-    <SlMenuItem checked>Option 2</SlMenuItem>
-    <SlMenuItem>Option 3</SlMenuItem>
-  </SlMenu>  
-);
-```
-
 ### Disabled
 
 Add the `disabled` attribute to disable the menu item so it cannot be selected.
 
 ```html preview
-<sl-menu style="max-width: 200px; border: solid 1px var(--sl-panel-border-color); background: var(--sl-panel-background-color); border-radius: var(--sl-border-radius-medium);">
+<sl-menu style="max-width: 200px;">
   <sl-menu-item>Option 1</sl-menu-item>
   <sl-menu-item disabled>Option 2</sl-menu-item>
   <sl-menu-item>Option 3</sl-menu-item>
@@ -107,23 +63,14 @@ Add the `disabled` attribute to disable the menu item so it cannot be selected.
 ```
 
 ```jsx react
-import { 
-  SlMenu,
-  SlMenuItem
-} from '@shoelace-style/shoelace/dist/react';
+import { SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlMenu 
-    style={{
-      maxWidth: '200px',
-      border: 'solid 1px var(--sl-panel-border-color)',
-      borderRadius: 'var(--sl-border-radius-medium)'
-    }}
-  >
+  <SlMenu style={{ maxWidth: '200px' }}>
     <SlMenuItem>Option 1</SlMenuItem>
     <SlMenuItem disabled>Option 2</SlMenuItem>
     <SlMenuItem>Option 3</SlMenuItem>
-  </SlMenu>  
+  </SlMenu>
 );
 ```
 
@@ -132,7 +79,7 @@ const App = () => (
 Add content to the start and end of menu items using the `prefix` and `suffix` slots.
 
 ```html preview
-<sl-menu style="max-width: 200px; border: solid 1px var(--sl-panel-border-color); background: var(--sl-panel-background-color); border-radius: var(--sl-border-radius-medium);">
+<sl-menu style="max-width: 200px;">
   <sl-menu-item>
     <sl-icon slot="prefix" name="house"></sl-icon>
     Home
@@ -154,22 +101,10 @@ Add content to the start and end of menu items using the `prefix` and `suffix` s
 ```
 
 ```jsx react
-import {
-  SlBadge,
-  SlDivider,
-  SlIcon,
-  SlMenu,
-  SlMenuItem
-} from '@shoelace-style/shoelace/dist/react';
+import { SlBadge, SlDivider, SlIcon, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlMenu 
-    style={{
-      maxWidth: '200px',
-      border: 'solid 1px var(--sl-panel-border-color)',
-      borderRadius: 'var(--sl-border-radius-medium)'
-    }}
-  >
+  <SlMenu style={{ maxWidth: '200px' }}>
     <SlMenuItem>
       <SlIcon slot="prefix" name="house" />
       Home
@@ -178,7 +113,9 @@ const App = () => (
     <SlMenuItem>
       <SlIcon slot="prefix" name="envelope" />
       Messages
-      <SlBadge slot="suffix" variant="primary" pill>12</SlBadge>
+      <SlBadge slot="suffix" variant="primary" pill>
+        12
+      </SlBadge>
     </SlMenuItem>
 
     <SlDivider />
@@ -187,7 +124,35 @@ const App = () => (
       <SlIcon slot="prefix" name="gear" />
       Settings
     </SlMenuItem>
-  </SlMenu>  
+  </SlMenu>
+);
+```
+
+### Checkbox Menu Items
+
+Set the `type` attribute to `checkbox` to create a menu item that will toggle on and off when selected. You can use the `checked` attribute to set the initial state.
+
+Checkbox menu items are visually indistinguishable from regular menu items. Their ability to be toggled is primarily inferred from context, much like you'd find in the menu of a native app.
+
+```html preview
+<sl-menu style="max-width: 200px;">
+  <sl-menu-item type="checkbox">Autosave</sl-menu-item>
+  <sl-menu-item type="checkbox" checked>Check Spelling</sl-menu-item>
+  <sl-menu-item type="checkbox">Word Wrap</sl-menu-item>
+</sl-menu>
+```
+
+```jsx react
+import { SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlMenu style={{ maxWidth: '200px' }}>
+    <SlMenuItem type="checkbox">Autosave</SlMenuItem>
+    <SlMenuItem type="checkbox" checked>
+      Check Spelling
+    </SlMenuItem>
+    <SlMenuItem type="checkbox">Word Wrap</SlMenuItem>
+  </SlMenu>
 );
 ```
 
@@ -196,10 +161,14 @@ const App = () => (
 The `value` attribute can be used to assign a hidden value, such as a unique identifier, to a menu item. When an item is selected, the `sl-select` event will be emitted and a reference to the item will be available at `event.detail.item`. You can use this reference to access the selected item's value, its checked state, and more.
 
 ```html preview
-<sl-menu class="menu-value" style="max-width: 200px; border: solid 1px var(--sl-panel-border-color); background: var(--sl-panel-background-color); border-radius: var(--sl-border-radius-medium);">
+<sl-menu class="menu-value" style="max-width: 200px;">
   <sl-menu-item value="opt-1">Option 1</sl-menu-item>
   <sl-menu-item value="opt-2">Option 2</sl-menu-item>
   <sl-menu-item value="opt-3">Option 3</sl-menu-item>
+  <sl-divider></sl-divider>
+  <sl-menu-item type="checkbox" value="opt-4">Checkbox 4</sl-menu-item>
+  <sl-menu-item type="checkbox" value="opt-5">Checkbox 5</sl-menu-item>
+  <sl-menu-item type="checkbox" value="opt-6">Checkbox 6</sl-menu-item>
 </sl-menu>
 
 <script>
@@ -208,23 +177,20 @@ The `value` attribute can be used to assign a hidden value, such as a unique ide
   menu.addEventListener('sl-select', event => {
     const item = event.detail.item;
 
-    // Toggle checked state
-    item.checked = !item.checked;
-
     // Log value
-    console.log(`Selected value: ${item.value}`);
+    if (item.type === 'checkbox') {
+      console.log(`Selected value: ${item.value} (${item.checked ? 'checked' : 'unchecked'})`);
+    } else {
+      console.log(`Selected value: ${item.value}`);
+    }
   });
 </script>
 ```
 
 ```jsx react
-import { 
-  SlMenu,
-  SlMenuItem
-} from '@shoelace-style/shoelace/dist/react';
+import { SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
-
   function handleSelect(event) {
     const item = event.detail.item;
 
@@ -236,14 +202,7 @@ const App = () => {
   }
 
   return (
-    <SlMenu 
-      style={{
-        maxWidth: '200px',
-        border: 'solid 1px var(--sl-panel-border-color)',
-        borderRadius: 'var(--sl-border-radius-medium)'
-      }}
-      onSlSelect={handleSelect}
-    >
+    <SlMenu style={{ maxWidth: '200px' }} onSlSelect={handleSelect}>
       <SlMenuItem value="opt-1">Option 1</SlMenuItem>
       <SlMenuItem value="opt-2">Option 2</SlMenuItem>
       <SlMenuItem value="opt-3">Option 3</SlMenuItem>

docs/components/menu-label.md

@@ -2,12 +2,8 @@
 
 [component-header:sl-menu-label]
 
-Menu labels are used to describe a group of menu items.
-
 ```html preview
-<sl-menu
-  style="max-width: 200px; border: solid 1px var(--sl-panel-border-color); background: var(--sl-panel-background-color); border-radius: var(--sl-border-radius-medium);"
->
+<sl-menu style="max-width: 200px;">
   <sl-menu-label>Fruits</sl-menu-label>
   <sl-menu-item value="apple">Apple</sl-menu-item>
   <sl-menu-item value="banana">Banana</sl-menu-item>
@@ -21,21 +17,10 @@ Menu labels are used to describe a group of menu items.
 ```
 
 ```jsx react
-import { 
-  SlDivider,
-  SlMenu,
-  SlMenuLabel,
-  SlMenuItem
-} from '@shoelace-style/shoelace/dist/react';
+import { SlDivider, SlMenu, SlMenuLabel, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlMenu 
-    style={{
-      maxWidth: '200px',
-      border: 'solid 1px var(--sl-panel-border-color)',
-      borderRadius: 'var(--sl-border-radius-medium)'
-    }}
-  >
+  <SlMenu style={{ maxWidth: '200px' }}>
     <SlMenuLabel>Fruits</SlMenuLabel>
     <SlMenuItem value="apple">Apple</SlMenuItem>
     <SlMenuItem value="banana">Banana</SlMenuItem>
@@ -45,7 +30,7 @@ const App = () => (
     <SlMenuItem value="broccoli">Broccoli</SlMenuItem>
     <SlMenuItem value="carrot">Carrot</SlMenuItem>
     <SlMenuItem value="zucchini">Zucchini</SlMenuItem>
-  </SlMenu>  
+  </SlMenu>
 );
 ```
 

docs/components/menu.md

@@ -2,12 +2,10 @@
 
 [component-header:sl-menu]
 
-Menus provide a list of options for the user to choose from.
-
 You can use [menu items](/components/menu-item), [menu labels](/components/menu-label), and [dividers](/components/divider) to compose a menu. Menus support keyboard interactions, including type-to-select an option.
 
 ```html preview
-<sl-menu style="max-width: 200px; border: solid 1px var(--sl-panel-border-color); background: var(--sl-panel-background-color); border-radius: var(--sl-border-radius-medium);">
+<sl-menu style="max-width: 200px;">
   <sl-menu-item value="undo">Undo</sl-menu-item>
   <sl-menu-item value="redo">Redo</sl-menu-item>
   <sl-divider></sl-divider>
@@ -19,20 +17,10 @@ You can use [menu items](/components/menu-item), [menu labels](/components/menu-
 ```
 
 ```jsx react
-import { 
-  SlDivider,
-  SlMenu,
-  SlMenuItem
-} from '@shoelace-style/shoelace/dist/react';
+import { SlDivider, SlMenu, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlMenu 
-    style={{
-      maxWidth: '200px',
-      border: 'solid 1px var(--sl-panel-border-color)',
-      borderRadius: 'var(--sl-border-radius-medium)'
-    }}
-  >
+  <SlMenu style={{ maxWidth: '200px' }}>
     <SlMenuItem value="undo">Undo</SlMenuItem>
     <SlMenuItem value="redo">Redo</SlMenuItem>
     <SlDivider />
@@ -40,7 +28,7 @@ const App = () => (
     <SlMenuItem value="copy">Copy</SlMenuItem>
     <SlMenuItem value="paste">Paste</SlMenuItem>
     <SlMenuItem value="delete">Delete</SlMenuItem>
-  </SlMenu>  
+  </SlMenu>
 );
 ```
 

docs/components/mutation-observer.md

@@ -2,30 +2,28 @@
 
 [component-header:sl-mutation-observer]
 
-The Mutation Observer component offers a thin, declarative interface to the [`MutationObserver API`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver).
-
 The mutation observer will report changes to the content it wraps through the `sl-mutation` event. When emitted, a collection of [MutationRecord](https://developer.mozilla.org/en-US/docs/Web/API/MutationRecord) objects will be attached to `event.detail` that contains information about how it changed.
 
 ```html preview
 <div class="mutation-overview">
-  <sl-mutation-observer attr="type">
+  <sl-mutation-observer attr="variant">
     <sl-button variant="primary">Click to mutate</sl-button>
   </sl-mutation-observer>
 
-  <br>
+  <br />
   👆 Click the button and watch the console
 
   <script>
     const container = document.querySelector('.mutation-overview');
     const mutationObserver = container.querySelector('sl-mutation-observer');
     const button = container.querySelector('sl-button');
-    const types = ['primary', 'success', 'neutral', 'warning', 'danger']; 
+    const variants = ['primary', 'success', 'neutral', 'warning', 'danger'];
     let clicks = 0;
 
-    // Change the button's type attribute
+    // Change the button's variant attribute
     button.addEventListener('click', () => {
       clicks++;
-      button.setAttribute('type', types[clicks % types.length]);
+      button.setAttribute('variant', variants[clicks % variants.length]);
     });
 
     // Log mutations
@@ -57,24 +55,23 @@ const css = `
   }
 `;
 
-const types = ['primary', 'success', 'neutral', 'warning', 'danger']; 
+const variants = ['primary', 'success', 'neutral', 'warning', 'danger'];
 let clicks = 0;
 
 const App = () => {
-  const [type, setType] = useState('primary');
+  const [variant, setVariant] = useState('primary');
 
   function handleClick() {
     clicks++;
-    setType(types[clicks % types.length]);
+    setVariant(variants[clicks % variants.length]);
   }
 
   return (
     <>
-      <SlMutationObserver 
-        attr="*"
-        onSlMutation={event => console.log(event.detail)}
-      >
-        <SlButton variant={type} onClick={handleClick}>Click to mutate</SlButton>
+      <SlMutationObserver attr="*" onSlMutation={event => console.log(event.detail)}>
+        <SlButton variant={variant} onClick={handleClick}>
+          Click to mutate
+        </SlButton>
       </SlMutationObserver>
 
       <style>{css}</style>
@@ -134,7 +131,7 @@ Use the `child-list` attribute to watch for new child elements that are added or
   <style>
     .mutation-child-list .buttons {
       display: flex;
-      gap: .25rem;
+      gap: 0.25rem;
       flex-wrap: wrap;
       margin-bottom: 1rem;
     }
@@ -171,12 +168,11 @@ const App = () => {
   return (
     <>
       <div className="mutation-child-list">
-        <SlMutationObserver 
-          child-list 
-          onSlMutation={event => console.log(event.detail)}
-        >
+        <SlMutationObserver child-list onSlMutation={event => console.log(event.detail)}>
           <div className="buttons">
-            <SlButton variant="primary" onClick={addButton}>Add button</SlButton>
+            <SlButton variant="primary" onClick={addButton}>
+              Add button
+            </SlButton>
             {buttonIds.map(id => (
               <SlButton key={id} variant="default" onClick={() => removeButton(id)}>
                 {id}
@@ -185,7 +181,6 @@ const App = () => {
           </div>
         </SlMutationObserver>
       </div>
-
       👆 Add and remove buttons and watch the console
       <style>{css}</style>
     </>

docs/components/option.md

@@ -0,0 +1,79 @@
+# Option
+
+[component-header:sl-option]
+
+```html preview
+<sl-select label="Select one">
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
+</sl-select>
+```
+
+```jsx react
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlSelect>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
+  </SlSelect>
+);
+```
+
+## Examples
+
+### Disabled
+
+Use the `disabled` attribute to disable an option and prevent it from being selected.
+
+```html preview
+<sl-select label="Select one">
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2" disabled>Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
+</sl-select>
+```
+
+```jsx react
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlSelect>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2" disabled>
+      Option 2
+    </SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
+  </SlSelect>
+);
+```
+
+### Prefix & Suffix
+
+Add icons to the start and end of menu items using the `prefix` and `suffix` slots.
+
+```html preview
+<sl-select label="Select one">
+  <sl-option value="option-1">
+    <sl-icon slot="prefix" name="envelope"></sl-icon>
+    Email
+    <sl-icon slot="suffix" name="patch-check"></sl-icon>
+  </sl-option>
+
+  <sl-option value="option-2">
+    <sl-icon slot="prefix" name="telephone"></sl-icon>
+    Phone
+    <sl-icon slot="suffix" name="patch-check"></sl-icon>
+  </sl-option>
+
+  <sl-option value="option-3">
+    <sl-icon slot="prefix" name="chat-dots"></sl-icon>
+    Chat
+    <sl-icon slot="suffix" name="patch-check"></sl-icon>
+  </sl-option>
+</sl-select>
+```
+
+[component-metadata:sl-option]

docs/components/progress-bar.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-progress-bar]
 
-Progress bars are used to show the status of an ongoing operation.
-
 ```html preview
 <sl-progress-bar value="50"></sl-progress-bar>
 ```
@@ -11,32 +9,11 @@ Progress bars are used to show the status of an ongoing operation.
 ```jsx react
 import { SlProgressBar } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlProgressBar value={50} />
-);
+const App = () => <SlProgressBar value={50} />;
 ```
 
 ## Examples
 
-### Custom Height
-
-Use the `--height` custom property to set the progress bar's height.
-
-```html preview
-<sl-progress-bar value="50" style="--height: 6px;"></sl-progress-bar>
-```
-
-```jsx react
-import { SlProgressBar } from '@shoelace-style/shoelace/dist/react';
-
-const App = () => (
-  <SlProgressBar 
-    value={50}
-    style={{ '--height': '6px' }}
-  />
-);
-```
-
 ### Labels
 
 Use the `label` attribute to label the progress bar and tell assistive devices how to announce it.
@@ -48,12 +25,21 @@ Use the `label` attribute to label the progress bar and tell assistive devices h
 ```jsx react
 import { SlProgressBar } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlProgressBar
-    value="50" 
-    label="Upload progress"
-  />
-);
+const App = () => <SlProgressBar value="50" label="Upload progress" />;
+```
+
+### Custom Height
+
+Use the `--height` custom property to set the progress bar's height.
+
+```html preview
+<sl-progress-bar value="50" style="--height: 6px;"></sl-progress-bar>
+```
+
+```jsx react
+import { SlProgressBar } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => <SlProgressBar value={50} style={{ '--height': '6px' }} />;
 ```
 
 ### Showing Values
@@ -63,10 +49,10 @@ Use the default slot to show a value.
 ```html preview
 <sl-progress-bar value="50" class="progress-bar-values">50%</sl-progress-bar>
 
-<br>
+<br />
 
-<sl-button circle><sl-icon name="dash"></sl-icon></sl-button>
-<sl-button circle><sl-icon name="plus"></sl-icon></sl-button>
+<sl-button circle><sl-icon name="dash" label="Decrease"></sl-icon></sl-button>
+<sl-button circle><sl-icon name="plus" label="Increase"></sl-icon></sl-button>
 
 <script>
   const progressBar = document.querySelector('.progress-bar-values');
@@ -80,7 +66,7 @@ Use the default slot to show a value.
   });
 
   subtractButton.addEventListener('click', () => {
-    const value = Math.max(0, progressBar.value - 10)
+    const value = Math.max(0, progressBar.value - 10);
     progressBar.value = value;
     progressBar.textContent = `${value}%`;
   });
@@ -89,11 +75,7 @@ Use the default slot to show a value.
 
 ```jsx react
 import { useState } from 'react';
-import { 
-  SlButton,
-  SlIcon,
-  SlProgressBar
-} from '@shoelace-style/shoelace/dist/react';
+import { SlButton, SlIcon, SlProgressBar } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [value, setValue] = useState(50);
@@ -107,18 +89,16 @@ const App = () => {
 
   return (
     <>
-      <SlProgressBar value={value}>
-        {value}%
-      </SlProgressBar>
+      <SlProgressBar value={value}>{value}%</SlProgressBar>
 
       <br />
 
       <SlButton circle onClick={() => adjustValue(-10)}>
-        <SlIcon name="dash" />
+        <SlIcon name="dash" label="Decrease" />
       </SlButton>
 
       <SlButton circle onClick={() => adjustValue(10)}>
-        <SlIcon name="plus" />
+        <SlIcon name="plus" label="Increase" />
       </SlButton>
     </>
   );
@@ -136,9 +116,7 @@ The `indeterminate` attribute can be used to inform the user that the operation
 ```jsx react
 import { SlProgressBar } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlProgressBar indeterminate />
-);
+const App = () => <SlProgressBar indeterminate />;
 ```
 
 [component-metadata:sl-progress-bar]

docs/components/progress-ring.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-progress-ring]
 
-Progress rings are used to show the progress of a determinate operation in a circular fashion.
-
 ```html preview
 <sl-progress-ring value="25"></sl-progress-ring>
 ```
@@ -11,9 +9,7 @@ Progress rings are used to show the progress of a determinate operation in a cir
 ```jsx react
 import { SlProgressRing } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlProgressRing value="25" />
-);
+const App = () => <SlProgressRing value="25" />;
 ```
 
 ## Examples
@@ -29,31 +25,21 @@ Use the `--size` custom property to set the diameter of the progress ring.
 ```jsx react
 import { SlProgressRing } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlProgressRing 
-    value="50" 
-    style={{ '--size': '200px' }}
-  />
-);
+const App = () => <SlProgressRing value="50" style={{ '--size': '200px' }} />;
 ```
 
-### Track Width
+### Track and Indicator Width
 
-Use the `--track-width` custom property to set the width of the progress ring's track.
+Use the `--track-width` and `--indicator-width` custom properties to set the width of the progress ring's track and indicator.
 
 ```html preview
-<sl-progress-ring value="50" style="--track-width: 10px;"></sl-progress-ring>
+<sl-progress-ring value="50" style="--track-width: 6px; --indicator-width: 12px;"></sl-progress-ring>
 ```
 
 ```jsx react
 import { SlProgressRing } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlProgressRing 
-    value="50" 
-    style={{ '--track-width': '10px' }}
-  />
-);
+const App = () => <SlProgressRing value="50" style={{ '--track-width': '6px', '--indicator-width': '12px' }} />;
 ```
 
 ### Colors
@@ -61,8 +47,8 @@ const App = () => (
 To change the color, use the `--track-color` and `--indicator-color` custom properties.
 
 ```html preview
-<sl-progress-ring 
-  value="50" 
+<sl-progress-ring
+  value="50"
   style="
     --track-color: pink; 
     --indicator-color: deeppink;
@@ -74,9 +60,9 @@ To change the color, use the `--track-color` and `--indicator-color` custom prop
 import { SlProgressRing } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlProgressRing 
-    value="50" 
-    style={{ 
+  <SlProgressRing
+    value="50"
+    style={{
       '--track-color': 'pink',
       '--indicator-color': 'deeppink'
     }}
@@ -95,12 +81,7 @@ Use the `label` attribute to label the progress ring and tell assistive devices
 ```jsx react
 import { SlProgressRing } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlProgressRing 
-    value="50" 
-    label="Upload progress"
-  />
-);
+const App = () => <SlProgressRing value="50" label="Upload progress" />;
 ```
 
 ### Showing Values
@@ -110,10 +91,10 @@ Use the default slot to show a label inside the progress ring.
 ```html preview
 <sl-progress-ring value="50" class="progress-ring-values" style="margin-bottom: .5rem;">50%</sl-progress-ring>
 
-<br>
+<br />
 
-<sl-button circle><sl-icon name="dash"></sl-icon></sl-button>
-<sl-button circle><sl-icon name="plus"></sl-icon></sl-button>
+<sl-button circle><sl-icon name="dash" label="Decrease"></sl-icon></sl-button>
+<sl-button circle><sl-icon name="plus" label="Increase"></sl-icon></sl-button>
 
 <script>
   const progressRing = document.querySelector('.progress-ring-values');
@@ -127,7 +108,7 @@ Use the default slot to show a label inside the progress ring.
   });
 
   subtractButton.addEventListener('click', () => {
-    const value = Math.max(0, progressRing.value - 10)
+    const value = Math.max(0, progressRing.value - 10);
     progressRing.value = value;
     progressRing.textContent = `${value}%`;
   });
@@ -136,11 +117,7 @@ Use the default slot to show a label inside the progress ring.
 
 ```jsx react
 import { useState } from 'react';
-import { 
-  SlButton,
-  SlIcon,
-  SlProgressRing
-} from '@shoelace-style/shoelace/dist/react';
+import { SlButton, SlIcon, SlProgressRing } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => {
   const [value, setValue] = useState(50);
@@ -154,21 +131,18 @@ const App = () => {
 
   return (
     <>
-      <SlProgressRing 
-        value={value} 
-        style={{ marginBottom: '.5rem' }}
-      >
+      <SlProgressRing value={value} style={{ marginBottom: '.5rem' }}>
         {value}%
       </SlProgressRing>
 
       <br />
 
       <SlButton circle onClick={() => adjustValue(-10)}>
-        <SlIcon name="dash" />
+        <SlIcon name="dash" label="Decrease" />
       </SlButton>
 
       <SlButton circle onClick={() => adjustValue(10)}>
-        <SlIcon name="plus" />
+        <SlIcon name="plus" label="Increase" />
       </SlButton>
     </>
   );

docs/components/qr-code.md

@@ -2,16 +2,14 @@
 
 [component-header:sl-qr-code]
 
-Generates a [QR code](https://www.qrcode.com/) and renders it using the [Canvas API](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API).
-
 QR codes are useful for providing small pieces of information to users who can quickly scan them with a smartphone. Most smartphones have built-in QR code scanners, so simply pointing the camera at a QR code will decode it and allow the user to visit a website, dial a phone number, read a message, etc.
 
 ```html preview
 <div class="qr-overview">
   <sl-qr-code value="https://shoelace.style/" label="Scan this code to visit Shoelace on the web!"></sl-qr-code>
-  <br>
+  <br />
 
-  <sl-input maxlength="255" clearable></sl-input>
+  <sl-input maxlength="255" clearable label="Value"></sl-input>
 </div>
 
 <script>
@@ -19,8 +17,10 @@ QR codes are useful for providing small pieces of information to users who can q
   const qrCode = container.querySelector('sl-qr-code');
   const input = container.querySelector('sl-input');
 
-  input.value = qrCode.value;
-  input.addEventListener('sl-input', () => qrCode.value = input.value);
+  customElements.whenDefined('sl-qr-code').then(() => {
+    input.value = qrCode.value;
+    input.addEventListener('sl-input', () => (qrCode.value = input.value));
+  });
 </script>
 
 <style>
@@ -79,9 +79,7 @@ Use the `fill` and `background` attributes to modify the QR code's colors. You s
 ```jsx react
 import { SlQrCode } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlQrCode value="https://shoelace.style/" fill="deeppink" background="white" />
-);
+const App = () => <SlQrCode value="https://shoelace.style/" fill="deeppink" background="white" />;
 ```
 
 ### Size
@@ -95,9 +93,7 @@ Use the `size` attribute to change the size of the QR code.
 ```jsx react
 import { SlQrCode } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlQrCode value="https://shoelace.style/" size="64" />
-);
+const App = () => <SlQrCode value="https://shoelace.style/" size="64" />;
 ```
 
 ### Radius
@@ -111,9 +107,7 @@ Create a rounded effect with the `radius` attribute.
 ```jsx react
 import { SlQrCode } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlQrCode value="https://shoelace.style/" radius="0.5" />
-);
+const App = () => <SlQrCode value="https://shoelace.style/" radius="0.5" />;
 ```
 
 ### Error Correction

docs/components/radio-button.md

@@ -0,0 +1,295 @@
+# Radio Button
+
+[component-header:sl-radio-button]
+
+Radio buttons are designed to be used with [radio groups](/components/radio-group). When a radio button has focus, the arrow keys can be used to change the selected option just like standard radio controls.
+
+```html preview
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio-button value="1">Option 1</sl-radio-button>
+  <sl-radio-button value="2">Option 2</sl-radio-button>
+  <sl-radio-button value="3">Option 3</sl-radio-button>
+</sl-radio-group>
+```
+
+```jsx react
+import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadioButton value="1">Option 1</SlRadioButton>
+    <SlRadioButton value="2">Option 2</SlRadioButton>
+    <SlRadioButton value="3">Option 3</SlRadioButton>
+  </SlRadioGroup>
+);
+```
+
+## Examples
+
+### Checked States
+
+To set the initial value and checked state, use the `value` attribute on the containing radio group.
+
+```html preview
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio-button value="1">Option 1</sl-radio-button>
+  <sl-radio-button value="2">Option 2</sl-radio-button>
+  <sl-radio-button value="3">Option 3</sl-radio-button>
+</sl-radio-group>
+```
+
+```jsx react
+import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadioButton value="1">Option 1</SlRadioButton>
+    <SlRadioButton value="2">Option 2</SlRadioButton>
+    <SlRadioButton value="3">Option 3</SlRadioButton>
+  </SlRadioGroup>
+);
+```
+
+### Disabled
+
+Use the `disabled` attribute to disable a radio button.
+
+```html preview
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio-button value="1">Option 1</sl-radio-button>
+  <sl-radio-button value="2" disabled>Option 2</sl-radio-button>
+  <sl-radio-button value="3">Option 3</sl-radio-button>
+</sl-radio-group>
+```
+
+```jsx react
+import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadioButton value="1">Option 1</SlRadioButton>
+    <SlRadioButton value="2" disabled>
+      Option 2
+    </SlRadioButton>
+    <SlRadioButton value="3">Option 3</SlRadioButton>
+  </SlRadioGroup>
+);
+```
+
+### Sizes
+
+Use the `size` attribute to change a radio button's size.
+
+```html preview
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio-button size="small" value="1">Option 1</sl-radio-button>
+  <sl-radio-button size="small" value="2">Option 2</sl-radio-button>
+  <sl-radio-button size="small" value="3">Option 3</sl-radio-button>
+</sl-radio-group>
+
+<br />
+
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio-button size="medium" value="1">Option 1</sl-radio-button>
+  <sl-radio-button size="medium" value="2">Option 2</sl-radio-button>
+  <sl-radio-button size="medium" value="3">Option 3</sl-radio-button>
+</sl-radio-group>
+
+<br />
+
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio-button size="large" value="1">Option 1</sl-radio-button>
+  <sl-radio-button size="large" value="2">Option 2</sl-radio-button>
+  <sl-radio-button size="large" value="3">Option 3</sl-radio-button>
+</sl-radio-group>
+```
+
+```jsx react
+import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadioButton size="small" value="1">Option 1</SlRadioButton>
+    <SlRadioButton size="small" value="2">Option 2</SlRadioButton>
+    <SlRadioButton size="small" value="3">Option 3</SlRadioButton>
+  </SlRadioGroup>
+
+  <br />
+
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadioButton size="medium" value="1">Option 1</SlRadioButton>
+    <SlRadioButton size="medium" value="2">Option 2</SlRadioButton>
+    <SlRadioButton size="medium" value="3">Option 3</SlRadioButton>
+  </SlRadioGroup>
+
+  <br />
+
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadioButton size="large" value="1">Option 1</SlRadioButton>
+    <SlRadioButton size="large" value="2">Option 2</SlRadioButton>
+    <SlRadioButton size="large" value="3">Option 3</SlRadioButton>
+  </SlRadioGroup>
+);
+```
+
+### Pill Buttons
+
+Use the `pill` attribute to give radio buttons rounded edges.
+
+```html preview
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio-button pill size="small" value="1">Option 1</sl-radio-button>
+  <sl-radio-button pill size="small" value="2">Option 2</sl-radio-button>
+  <sl-radio-button pill size="small" value="3">Option 3</sl-radio-button>
+</sl-radio-group>
+
+<br />
+
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio-button pill size="medium" value="1">Option 1</sl-radio-button>
+  <sl-radio-button pill size="medium" value="2">Option 2</sl-radio-button>
+  <sl-radio-button pill size="medium" value="3">Option 3</sl-radio-button>
+</sl-radio-group>
+
+<br />
+
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio-button pill size="large" value="1">Option 1</sl-radio-button>
+  <sl-radio-button pill size="large" value="2">Option 2</sl-radio-button>
+  <sl-radio-button pill size="large" value="3">Option 3</sl-radio-button>
+</sl-radio-group>
+```
+
+```jsx react
+import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadioButton pill size="small" value="1">Option 1</SlRadioButton>
+    <SlRadioButton pill size="small" value="2">Option 2</SlRadioButton>
+    <SlRadioButton pill size="small" value="3">Option 3</SlRadioButton>
+  </SlRadioGroup>
+
+  <br />
+
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadioButton pill size="medium" value="1">Option 1</SlRadioButton>
+    <SlRadioButton pill size="medium" value="2">Option 2</SlRadioButton>
+    <SlRadioButton pill size="medium" value="3">Option 3</SlRadioButton>
+  </SlRadioGroup>
+
+  <br />
+
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadioButton pill size="large" value="1">Option 1</SlRadioButton>
+    <SlRadioButton pill size="large" value="2">Option 2</SlRadioButton>
+    <SlRadioButton pill size="large" value="3">Option 3</SlRadioButton>
+  </SlRadioGroup>
+);
+```
+
+### Prefix and Suffix Icons
+
+Use the `prefix` and `suffix` slots to add icons.
+
+```html preview
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio-button value="1">
+    <sl-icon slot="prefix" name="archive"></sl-icon>
+    Option 1
+  </sl-radio-button>
+
+  <sl-radio-button value="2">
+    <sl-icon slot="suffix" name="bag"></sl-icon>
+    Option 2
+  </sl-radio-button>
+
+  <sl-radio-button value="3">
+    <sl-icon slot="prefix" name="gift"></sl-icon>
+    <sl-icon slot="suffix" name="cart"></sl-icon>
+    Option 3
+  </sl-radio-button>
+</sl-radio-group>
+```
+
+```jsx react
+import { SlIcon, SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadioButton value="1">
+      <SlIcon slot="prefix" name="archive" />
+      Option 1
+    </SlRadioButton>
+
+    <SlRadioButton value="2">
+      <SlIcon slot="suffix" name="bag" />
+      Option 2
+    </SlRadioButton>
+
+    <SlRadioButton value="3">
+      <SlIcon slot="prefix" name="gift" />
+      <SlIcon slot="suffix" name="cart" />
+      Option 3
+    </SlRadioButton>
+  </SlRadioGroup>
+);
+```
+
+### Buttons with Icons
+
+You can omit button labels and use icons instead. Make sure to set a `label` attribute on each icon so screen readers will announce each option correctly.
+
+```html preview
+<sl-radio-group label="Select an option" name="a" value="neutral">
+  <sl-radio-button value="angry">
+    <sl-icon name="emoji-angry" label="Angry"></sl-icon>
+  </sl-radio-button>
+
+  <sl-radio-button value="sad">
+    <sl-icon name="emoji-frown" label="Sad"></sl-icon>
+  </sl-radio-button>
+
+  <sl-radio-button value="neutral">
+    <sl-icon name="emoji-neutral" label="Neutral"></sl-icon>
+  </sl-radio-button>
+
+  <sl-radio-button value="happy">
+    <sl-icon name="emoji-smile" label="Happy"></sl-icon>
+  </sl-radio-button>
+
+  <sl-radio-button value="laughing">
+    <sl-icon name="emoji-laughing" label="Laughing"></sl-icon>
+  </sl-radio-button>
+</sl-radio-group>
+```
+
+```jsx react
+import { SlIcon, SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRadioGroup label="Select an option" name="a" value="neutral">
+    <SlRadioButton value="angry">
+      <SlIcon name="emoji-angry" label="Angry" />
+    </SlRadioButton>
+
+    <SlRadioButton value="sad">
+      <SlIcon name="emoji-frown" label="Sad" />
+    </SlRadioButton>
+
+    <SlRadioButton value="neutral">
+      <SlIcon name="emoji-neutral" label="Neutral" />
+    </SlRadioButton>
+
+    <SlRadioButton value="happy">
+      <SlIcon name="emoji-smile" label="Happy" />
+    </SlRadioButton>
+
+    <SlRadioButton value="laughing">
+      <SlIcon name="emoji-laughing" label="Laughing" />
+    </SlRadioButton>
+  </SlRadioGroup>
+);
+```
+
+[component-metadata:sl-radio-button]

docs/components/radio-group.md

@@ -2,11 +2,9 @@
 
 [component-header:sl-radio-group]
 
-Radio Groups are used to group multiple radios so they function as a single control.
-
 ```html preview
-<sl-radio-group label="Select an option">
-  <sl-radio value="1" checked>Option 1</sl-radio>
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio value="1">Option 1</sl-radio>
   <sl-radio value="2">Option 2</sl-radio>
   <sl-radio value="3">Option 3</sl-radio>
 </sl-radio-group>
@@ -16,8 +14,8 @@ Radio Groups are used to group multiple radios so they function as a single cont
 import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlRadioGroup label="Select an option">
-    <SlRadio value="1" checked>Option 1</SlRadio>
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadio value="1">Option 1</SlRadio>
     <SlRadio value="2">Option 2</SlRadio>
     <SlRadio value="3">Option 3</SlRadio>
   </SlRadioGroup>
@@ -26,13 +24,13 @@ const App = () => (
 
 ## Examples
 
-### Showing the Fieldset
+### Help Text
 
-You can show a fieldset and legend that wraps the radio group using the `fieldset` attribute.
+Add descriptive help text to a radio group with the `help-text` attribute. For help texts that contain HTML, use the `help-text` slot instead.
 
 ```html preview
-<sl-radio-group label="Select an option" fieldset>
-  <sl-radio value="1" checked>Option 1</sl-radio>
+<sl-radio-group label="Select an option" help-text="Choose the most appropriate option." name="a" value="1">
+  <sl-radio value="1">Option 1</sl-radio>
   <sl-radio value="2">Option 2</sl-radio>
   <sl-radio value="3">Option 3</sl-radio>
 </sl-radio-group>
@@ -42,11 +40,193 @@ You can show a fieldset and legend that wraps the radio group using the `fieldse
 import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlRadioGroup label="Select an option" fieldset>
-    <SlRadio value="1" checked>Option 1</SlRadio>
+  <SlRadioGroup label="Select an option" help-text="Choose the most appropriate option." name="a" value="1">
+    <SlRadio value="1">Option 1</SlRadio>
     <SlRadio value="2">Option 2</SlRadio>
     <SlRadio value="3">Option 3</SlRadio>
   </SlRadioGroup>
 );
 ```
+
+### Radio Buttons
+
+[Radio buttons](/components/radio-button) offer an alternate way to display radio controls. In this case, an internal [button group](/components/button-group) is used to group the buttons into a single, cohesive control.
+
+```html preview
+<sl-radio-group label="Select an option" help-text="Select an option that makes you proud." name="a" value="1">
+  <sl-radio-button value="1">Option 1</sl-radio-button>
+  <sl-radio-button value="2">Option 2</sl-radio-button>
+  <sl-radio-button value="3">Option 3</sl-radio-button>
+</sl-radio-group>
+```
+
+```jsx react
+import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadioButton value="1">Option 1</SlRadioButton>
+    <SlRadioButton value="2">Option 2</SlRadioButton>
+    <SlRadioButton value="3">Option 3</SlRadioButton>
+  </SlRadioGroup>
+);
+```
+
+### Disabling Options
+
+Radios and radio buttons can be disabled by adding the `disabled` attribute to the respective options inside the radio group.
+
+```html preview
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio value="1">Option 1</sl-radio>
+  <sl-radio value="2" disabled>Option 2</sl-radio>
+  <sl-radio value="3">Option 3</sl-radio>
+</sl-radio-group>
+```
+
+```jsx react
+import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadio value="1">Option 1</SlRadio>
+    <SlRadio value="2" disabled>
+      Option 2
+    </SlRadio>
+    <SlRadio value="3">Option 3</SlRadio>
+  </SlRadioGroup>
+);
+```
+
+### Validation
+
+Setting the `required` attribute to make selecting an option mandatory. If a value has not been selected, it will prevent the form from submitting and display an error message.
+
+```html preview
+<form class="validation">
+  <sl-radio-group label="Select an option" name="a" required>
+    <sl-radio value="1">Option 1</sl-radio>
+    <sl-radio value="2">Option 2</sl-radio>
+    <sl-radio value="3">Option 3</sl-radio>
+  </sl-radio-group>
+  <br />
+  <sl-button type="submit" variant="primary">Submit</sl-button>
+</form>
+
+<script>
+  const form = document.querySelector('.validation');
+
+  // Handle form submit
+  form.addEventListener('submit', event => {
+    event.preventDefault();
+    alert('All fields are valid!');
+  });
+</script>
+```
+
+```jsx react
+import { SlButton, SlIcon, SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
+const App = () => {
+  function handleSubmit(event) {
+    event.preventDefault();
+    alert('All fields are valid!');
+  }
+
+  return (
+    <form class="custom-validity" onSubmit={handleSubmit}>
+      <SlRadioGroup label="Select an option" name="a" required onSlChange={handleChange}>
+        <SlRadio value="1">
+          Option 1
+        </SlRadio>
+        <SlRadiovalue="2">
+          Option 2
+        </SlRadio>
+        <SlRadio value="3">
+          Option 3
+        </SlRadio>
+      </SlRadioGroup>
+      <br />
+      <SlButton type="submit" variant="primary">
+        Submit
+      </SlButton>
+    </form>
+  );
+};
+```
+
+### Custom Validity
+
+Use the `setCustomValidity()` method to set a custom validation message. This will prevent the form from submitting and make the browser display the error message you provide. To clear the error, call this function with an empty string.
+
+```html preview
+<form class="custom-validity">
+  <sl-radio-group label="Select an option" name="a" value="1">
+    <sl-radio value="1">Not me</sl-radio>
+    <sl-radio value="2">Me neither</sl-radio>
+    <sl-radio value="3">Choose me</sl-radio>
+  </sl-radio-group>
+  <br />
+  <sl-button type="submit" variant="primary">Submit</sl-button>
+</form>
+
+<script>
+  const form = document.querySelector('.custom-validity');
+  const radioGroup = form.querySelector('sl-radio-group');
+  const errorMessage = 'You must choose the last option';
+
+  // Set initial validity as soon as the element is defined
+  customElements.whenDefined('sl-radio').then(() => {
+    radioGroup.setCustomValidity(errorMessage);
+  });
+
+  // Update validity when a selection is made
+  form.addEventListener('sl-change', () => {
+    const isValid = radioGroup.value === '3';
+    radioGroup.setCustomValidity(isValid ? '' : errorMessage);
+  });
+
+  // Handle form submit
+  form.addEventListener('submit', event => {
+    event.preventDefault();
+    alert('All fields are valid!');
+  });
+</script>
+```
+
+```jsx react
+import { useEffect, useRef } from 'react';
+import { SlButton, SlIcon, SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
+const App = () => {
+  const radioGroup = useRef(null);
+  const errorMessage = 'You must choose this option';
+
+  function handleChange() {
+    radioGroup.current.setCustomValidity(radioGroup.current.value === '3' ? '' : errorMessage);
+  }
+
+  function handleSubmit(event) {
+    event.preventDefault();
+    alert('All fields are valid!');
+  }
+
+  useEffect(() => {
+    radio.current.setCustomValidity(errorMessage);
+  }, []);
+
+  return (
+    <form class="custom-validity" onSubmit={handleSubmit}>
+      <SlRadioGroup ref={radioGroup} label="Select an option" name="a" value="1" onSlChange={handleChange}>
+        <SlRadio value="1">Not me</SlRadio>
+        <SlRadio value="2">Me neither</SlRadio>
+        <SlRadio value="3">Choose me</SlRadio>
+      </SlRadioGroup>
+      <br />
+      <SlButton type="submit" variant="primary">
+        Submit
+      </SlButton>
+    </form>
+  );
+};
+```
+
 [component-metadata:sl-radio-group]

docs/components/radio.md

@@ -2,13 +2,11 @@
 
 [component-header:sl-radio]
 
-Radios allow the user to select one option from a group of many.
-
-Radios are designed to be used with [radio groups](/components/radio-group). As such, all of the examples on this page utilize them to demonstrate their correct usage.
+Radios are designed to be used with [radio groups](/components/radio-group).
 
 ```html preview
-<sl-radio-group label="Select an option">
-  <sl-radio value="1" checked>Option 1</sl-radio>
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio value="1">Option 1</sl-radio>
   <sl-radio value="2">Option 2</sl-radio>
   <sl-radio value="3">Option 3</sl-radio>
 </sl-radio-group>
@@ -18,28 +16,51 @@ Radios are designed to be used with [radio groups](/components/radio-group). As
 import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlRadioGroup label="Select an option">
-    <SlRadio value="1" checked>Option 1</SlRadio>
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadio value="1">Option 1</SlRadio>
     <SlRadio value="2">Option 2</SlRadio>
     <SlRadio value="3">Option 3</SlRadio>
   </SlRadioGroup>
 );
 ```
 
-?> This component doesn't work with standard forms. Use [`<sl-form>`](/components/form) instead.
+?> This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
 
 ## Examples
 
+### Initial Value
+
+To set the initial value and checked state, use the `value` attribute on the containing radio group.
+
+```html preview
+<sl-radio-group label="Select an option" name="a" value="3">
+  <sl-radio value="1">Option 1</sl-radio>
+  <sl-radio value="2">Option 2</sl-radio>
+  <sl-radio value="3">Option 3</sl-radio>
+</sl-radio-group>
+```
+
+```jsx react
+import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRadioGroup label="Select an option" name="a" value="3">
+    <SlRadio value="1">Option 1</SlRadio>
+    <SlRadio value="2">Option 2</SlRadio>
+    <SlRadio value="3">Option 3</SlRadio>
+  </SlRadioGroup>
+);
+```
+
 ### Disabled
 
 Use the `disabled` attribute to disable a radio.
 
 ```html preview
-<sl-radio-group label="Select an option">
-  <sl-radio value="1" checked>Option 1</sl-radio>
-  <sl-radio value="2">Option 2</sl-radio>
+<sl-radio-group label="Select an option" name="a" value="1">
+  <sl-radio value="1">Option 1</sl-radio>
+  <sl-radio value="2" disabled>Option 2</sl-radio>
   <sl-radio value="3">Option 3</sl-radio>
-  <sl-radio value="4" disabled>Disabled</sl-radio>
 </sl-radio-group>
 ```
 
@@ -47,13 +68,38 @@ Use the `disabled` attribute to disable a radio.
 import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlRadioGroup label="Select an option">
-    <SlRadio value="1" checked>Option 1</SlRadio>
-    <SlRadio value="2">Option 2</SlRadio>
+  <SlRadioGroup label="Select an option" name="a" value="1">
+    <SlRadio value="1">Option 1</SlRadio>
+    <SlRadio value="2" disabled>
+      Option 2
+    </SlRadio>
     <SlRadio value="3">Option 3</SlRadio>
-    <SlRadio value="4" disabled>Disabled</SlRadio>
   </SlRadioGroup>
 );
 ```
 
+## Sizes
+
+Use the `size` attribute to change a radio's size.
+
+```html preview
+<sl-radio size="small">Small</sl-radio>
+<sl-radio size="medium">Medium</sl-radio>
+<sl-radio size="large">Large</sl-radio>
+```
+
+```jsx react
+import { SlRadio } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlRadio size="small">Small</SlRadio>
+    <br />
+    <SlRadio size="medium">Medium</SlRadio>
+    <br />
+    <SlRadio size="large">Large</SlRadio>
+  </>
+);
+```
+
 [component-metadata:sl-radio]

docs/components/range.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-range]
 
-Ranges allow the user to select a single value within a given range using a slider.
-
 ```html preview
 <sl-range></sl-range>
 ```
@@ -11,15 +9,41 @@ Ranges allow the user to select a single value within a given range using a slid
 ```jsx react
 import { SlRange } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlRange />
-);
+const App = () => <SlRange />;
 ```
 
-?> This component doesn't work with standard forms. Use [`<sl-form>`](/components/form) instead.
+?> This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
 
 ## Examples
 
+### Labels
+
+Use the `label` attribute to give the range an accessible label. For labels that contain HTML, use the `label` slot instead.
+
+```html preview
+<sl-range label="Volume" min="0" max="100"></sl-range>
+```
+
+```jsx react
+import { SlRange } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => <SlRange label="Volume" min={0} max={100} />;
+```
+
+### Help Text
+
+Add descriptive help text to a range with the `help-text` attribute. For help texts that contain HTML, use the `help-text` slot instead.
+
+```html preview
+<sl-range label="Volume" help-text="Controls the volume of the current song." min="0" max="100"></sl-range>
+```
+
+```jsx react
+import { SlRange } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => <SlRange label="Volume" help-text="Controls the volume of the current song." min={0} max={100} />;
+```
+
 ### Min, Max, and Step
 
 Use the `min` and `max` attributes to set the range's minimum and maximum values, respectively. The `step` attribute determines the value's interval when increasing and decreasing.
@@ -31,9 +55,7 @@ Use the `min` and `max` attributes to set the range's minimum and maximum values
 ```jsx react
 import { SlRange } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlRange min={0} max={10} step={1} />
-);
+const App = () => <SlRange min={0} max={10} step={1} />;
 ```
 
 ### Disabled
@@ -44,13 +66,10 @@ Use the `disabled` attribute to disable a slider.
 <sl-range disabled></sl-range>
 ```
 
-
 ```jsx react
 import { SlRange } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlRange disabled />
-);
+const App = () => <SlRange disabled />;
 ```
 
 ### Tooltip Placement
@@ -64,9 +83,7 @@ By default, the tooltip is shown on top. Set `tooltip` to `bottom` to show it be
 ```jsx react
 import { SlRange } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlRange tooltip="bottom" />
-);
+const App = () => <SlRange tooltip="bottom" />;
 ```
 
 ### Disable the Tooltip
@@ -80,9 +97,7 @@ To disable the tooltip, set `tooltip` to `none`.
 ```jsx react
 import { SlRange } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlRange tooltip="none" />
-);
+const App = () => <SlRange tooltip="none" />;
 ```
 
 ### Custom Track Colors
@@ -90,17 +105,19 @@ const App = () => (
 You can customize the active and inactive portions of the track using the `--track-color-active` and `--track-color-inactive` custom properties.
 
 ```html preview
-<sl-range style="
+<sl-range
+  style="
   --track-color-active: var(--sl-color-primary-600);
   --track-color-inactive: var(--sl-color-primary-100);
-"></sl-range>
+"
+></sl-range>
 ```
 
 ```jsx react
 import { SlRange } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlRange 
+  <SlRange
     style={{
       '--track-color-active': 'var(--sl-color-primary-600)',
       '--track-color-inactive': 'var(--sl-color-primary-200)'
@@ -109,6 +126,38 @@ const App = () => (
 );
 ```
 
+### Custom Track Offset
+
+You can customize the initial offset of the active track using the `--track-active-offset` custom property.
+
+```html preview
+<sl-range
+  min="-100"
+  max="100"
+  style="
+  --track-color-active: var(--sl-color-primary-600);
+  --track-color-inactive: var(--sl-color-primary-100);
+  --track-active-offset: 50%;
+"
+></sl-range>
+```
+
+```jsx react
+import { SlRange } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRange
+    min={-100}
+    max={100}
+    style={{
+      '--track-color-active': 'var(--sl-color-primary-600)',
+      '--track-color-inactive': 'var(--sl-color-primary-200)',
+      '--track-active-offset': '50%'
+    }}
+  />
+);
+```
+
 ### Custom Tooltip Formatter
 
 You can change the tooltip's content by setting the `tooltipFormatter` property to a function that accepts the range's value as an argument.
@@ -125,56 +174,7 @@ You can change the tooltip's content by setting the `tooltipFormatter` property
 ```jsx react
 import { SlRange } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlRange 
-    min={0}
-    max={100}
-    step={1}
-    tooltipFormatter={value => `Total - ${value}%`}
-  />
-);
-```
-
-### Labels
-
-Use the `label` attribute to give the range an accessible label. For labels that contain HTML, use the `label` slot instead.
-
-```html preview
-<sl-range label="Volume" min="0" max="100"></sl-input>
-```
-
-```jsx react
-import { SlRange } from '@shoelace-style/shoelace/dist/react';
-
-const App = () => (
-  <SlRange label="Volume" min={0} max={100} />
-);
-```
-
-### Help Text
-
-Add descriptive help text to a range with the `help-text` attribute. For help texts that contain HTML, use the `help-text` slot instead.
-
-```html preview
-<sl-range 
-  label="Volume" 
-  help-text="Controls the volume of the current song."
-  min="0"
-  max="100"
-></sl-input>
-```
-
-```jsx react
-import { SlRange } from '@shoelace-style/shoelace/dist/react';
-
-const App = () => (
-  <SlRange 
-    label="Volume" 
-    help-text="Controls the volume of the current song."
-    min={0}
-    max={100}
-  />
-);
+const App = () => <SlRange min={0} max={100} step={1} tooltipFormatter={value => `Total - ${value}%`} />;
 ```
 
 [component-metadata:sl-range]

docs/components/rating.md

@@ -2,36 +2,44 @@
 
 [component-header:sl-rating]
 
-Ratings give users a way to quickly view and provide feedback.
-
 ```html preview
-<sl-rating></sl-rating>
+<sl-rating label="Rating"></sl-rating>
 ```
 
 ```jsx react
 import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlRating />
-);
+const App = () => <SlRating label="Rating" />;
 ```
 
 ## Examples
 
+### Labels
+
+Ratings are commonly identified contextually, so labels aren't displayed. However, you should always provide one for assistive devices using the `label` attribute.
+
+```html preview
+<sl-rating label="Rate this component"></sl-rating>
+```
+
+```jsx react
+import { SlRating } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => <SlRating label="Rate this component" />;
+```
+
 ### Maximum Value
 
 Ratings are 0-5 by default. To change the maximum possible value, use the `max` attribute.
 
 ```html preview
-<sl-rating max="3"></sl-rating>
+<sl-rating label="Rating" max="3"></sl-rating>
 ```
 
 ```jsx react
 import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlRating max={3} />
-);
+const App = () => <SlRating label="Rating" max={3} />;
 ```
 
 ### Precision
@@ -39,31 +47,27 @@ const App = () => (
 Use the `precision` attribute to let users select fractional ratings.
 
 ```html preview
-<sl-rating precision="0.5" value="2.5"></sl-rating>
+<sl-rating label="Rating" precision="0.5" value="2.5"></sl-rating>
 ```
 
 ```jsx react
 import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlRating precision={0.5} value={2.5} />
-);
+const App = () => <SlRating label="Rating" precision={0.5} value={2.5} />;
 ```
 
-## Symbol Sizes
+### Symbol Sizes
 
 Set the `--symbol-size` custom property to adjust the size.
 
 ```html preview
-<sl-rating style="--symbol-size: 2rem;"></sl-rating>
+<sl-rating label="Rating" style="--symbol-size: 2rem;"></sl-rating>
 ```
 
 ```jsx react
 import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlRating style={{ '--symbol-size': '2rem' }} />
-);
+const App = () => <SlRating label="Rating" style={{ '--symbol-size': '2rem' }} />;
 ```
 
 ### Readonly
@@ -71,15 +75,13 @@ const App = () => (
 Use the `readonly` attribute to display a rating that users can't change.
 
 ```html preview
-<sl-rating readonly value="3"></sl-rating>
+<sl-rating label="Rating" readonly value="3"></sl-rating>
 ```
 
 ```jsx react
 import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlRating readonly value={3} />
-);
+const App = () => <SlRating label="Rating" readonly value={3} />;
 ```
 
 ### Disabled
@@ -87,49 +89,144 @@ const App = () => (
 Use the `disable` attribute to disable the rating.
 
 ```html preview
-<sl-rating disabled value="3"></sl-rating>
+<sl-rating label="Rating" disabled value="3"></sl-rating>
 ```
 
 ```jsx react
 import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlRating disabled value={3} />
-);
+const App = () => <SlRating label="Rating" disabled value={3} />;
+```
+
+### Detecting Hover
+
+Use the `sl-hover` event to detect when the user hovers over (or touch and drag) the rating. This lets you hook into values as the user interacts with the rating, but before they select a value.
+
+The event has a payload with `phase` and `value` properties. The `phase` property tells when hovering starts, moves to a new value, and ends. The `value` property tells what the rating's value would be if the user were to commit to the hovered value.
+
+```html preview
+<div class="detect-hover">
+  <sl-rating label="Rating"></sl-rating>
+  <span></span>
+</div>
+
+<script>
+  const rating = document.querySelector('.detect-hover > sl-rating');
+  const span = rating.nextElementSibling;
+  const terms = ['No rating', 'Terrible', 'Bad', 'OK', 'Good', 'Excellent'];
+
+  rating.addEventListener('sl-hover', event => {
+    span.textContent = terms[event.detail.value];
+
+    // Clear feedback when hovering stops
+    if (event.detail.phase === 'end') {
+      span.textContent = '';
+    }
+  });
+</script>
+
+<style>
+  .detect-hover span {
+    position: relative;
+    top: -4px;
+    left: 8px;
+    border-radius: var(--sl-border-radius-small);
+    background: var(--sl-color-neutral-900);
+    color: var(--sl-color-neutral-0);
+    text-align: center;
+    padding: 4px 6px;
+  }
+
+  .detect-hover span:empty {
+    display: none;
+  }
+</style>
+```
+
+```jsx react
+import { useState } from 'react';
+import { SlRating } from '@shoelace-style/shoelace/dist/react';
+
+const terms = ['No rating', 'Terrible', 'Bad', 'OK', 'Good', 'Excellent'];
+const css = `
+  .detect-hover span {
+    position: relative;
+    top: -4px;
+    left: 8px;
+    border-radius: var(--sl-border-radius-small);
+    background: var(--sl-color-neutral-900);
+    color: var(--sl-color-neutral-0);
+    text-align: center;
+    padding: 4px 6px;
+  }
+
+  .detect-hover span:empty {
+    display: none;
+  }
+`;
+
+function handleHover(event) {
+  rating.addEventListener('sl-hover', event => {
+    setFeedback(terms[event.detail.value]);
+
+    // Clear feedback when hovering stops
+    if (event.detail.phase === 'end') {
+      setFeedback('');
+    }
+  });
+}
+
+const App = () => {
+  const [feedback, setFeedback] = useState(true);
+
+  return (
+    <>
+      <div class="detect-hover">
+        <SlRating label="Rating" onSlHover={handleHover} />
+        <span>{feedback}</span>
+      </div>
+      <style>{css}</style>
+    </>
+  );
+};
 ```
 
 ### Custom Icons
 
+You can provide custom icons by passing a function to the `getSymbol` property.
+
 ```html preview
-<sl-rating class="rating-hearts" style="--symbol-color-active: #ff4136;"></sl-rating>
+<sl-rating label="Rating" class="rating-hearts" style="--symbol-color-active: #ff4136;"></sl-rating>
 
 <script>
   const rating = document.querySelector('.rating-hearts');
-  rating.getSymbol = () => '<sl-icon name="heart-fill"></sl-icon>'; 
+  rating.getSymbol = () => '<sl-icon name="heart-fill"></sl-icon>';
 </script>
 ```
 
 ```jsx react
-import '@shoelace-style/shoelace/dist/components/icon/icon';
 import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlRating 
+  <SlRating
+    label="Rating"
     getSymbol={() => '<sl-icon name="heart-fill"></sl-icon>'}
-    style={{ '--symbol-color-active': '#ff4136' }} 
+    style={{ '--symbol-color-active': '#ff4136' }}
   />
 );
 ```
 
 ### Value-based Icons
 
+You can also use the `getSymbol` property to render different icons based on value.
+
 ```html preview
-<sl-rating class="rating-emojis"></sl-rating>
+<sl-rating label="Rating" class="rating-emojis"></sl-rating>
 
 <script>
   const rating = document.querySelector('.rating-emojis');
 
-  rating.getSymbol = (value) => {
+  rating.getSymbol = value => {
     const icons = ['emoji-angry', 'emoji-frown', 'emoji-expressionless', 'emoji-smile', 'emoji-laughing'];
     return `<sl-icon name="${icons[value - 1]}"></sl-icon>`;
   };
@@ -137,7 +234,6 @@ const App = () => (
 ```
 
 ```jsx react
-import '@shoelace-style/shoelace/dist/components/icon/icon';
 import { SlRating } from '@shoelace-style/shoelace/dist/react';
 
 function getSymbol(value) {
@@ -145,9 +241,7 @@ function getSymbol(value) {
   return `<sl-icon name="${icons[value - 1]}"></sl-icon>`;
 }
 
-const App = () => (
-  <SlRating getSymbol={getSymbol} />
-);
+const App = () => <SlRating label="Rating" getSymbol={getSymbol} />;
 ```
 
 [component-metadata:sl-rating]

docs/components/relative-time.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-relative-time]
 
-Outputs a localized time phrase relative to the current date and time.
-
 Localization is handled by the browser's [`Intl.RelativeTimeFormat` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat). No language packs are required.
 
 ```html preview
@@ -14,17 +12,13 @@ Localization is handled by the browser's [`Intl.RelativeTimeFormat` API](https:/
 ```jsx react
 import { SlRelativeTime } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlRelativeTime date="2020-07-15T09:17:00-04:00" />
-);
+const App = () => <SlRelativeTime date="2020-07-15T09:17:00-04:00" />;
 ```
 
 The `date` attribute determines when the date/time is calculated from. It must be a string that [`Date.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse) can interpret or a [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) object set via JavaScript.
 
 ?> When using strings, avoid ambiguous dates such as `03/04/2020` which can be interpreted as March 4 or April 3 depending on the user's browser and locale. Instead, always use a valid [ISO 8601 date time string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse#Date_Time_String_Format) to ensure the date will be parsed properly by all clients.
 
-!> The `Intl.RelativeTimeFormat` API is available [in all major browsers](https://caniuse.com/mdn-javascript_builtins_intl_relativetimeformat), but it only became available to Safari in version 14. If you need to support Safari 13, you'll need to [use a polyfill](https://github.com/catamphetamine/relative-time-format).
-
 ## Examples
 
 ### Keeping Time in Sync
@@ -49,9 +43,7 @@ import { SlRelativeTime } from '@shoelace-style/shoelace/dist/react';
 
 const date = new Date(new Date().getTime() - 60000);
 
-const App = () => (
-  <SlRelativeTime date={date} sync />
-);
+const App = () => <SlRelativeTime date={date} sync />;
 ```
 
 ### Formatting Styles
@@ -59,8 +51,8 @@ const App = () => (
 You can change how the time is displayed using the `format` attribute. Note that some locales may display the same values for `narrow` and `short` formats.
 
 ```html preview
-<sl-relative-time date="2020-07-15T09:17:00-04:00" format="narrow"></sl-relative-time><br>
-<sl-relative-time date="2020-07-15T09:17:00-04:00" format="short"></sl-relative-time><br>
+<sl-relative-time date="2020-07-15T09:17:00-04:00" format="narrow"></sl-relative-time><br />
+<sl-relative-time date="2020-07-15T09:17:00-04:00" format="short"></sl-relative-time><br />
 <sl-relative-time date="2020-07-15T09:17:00-04:00" format="long"></sl-relative-time>
 ```
 
@@ -69,8 +61,10 @@ import { SlRelativeTime } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlRelativeTime date="2020-07-15T09:17:00-04:00" format="narrow" /><br />
-    <SlRelativeTime date="2020-07-15T09:17:00-04:00" format="short" /><br />
+    <SlRelativeTime date="2020-07-15T09:17:00-04:00" format="narrow" />
+    <br />
+    <SlRelativeTime date="2020-07-15T09:17:00-04:00" format="short" />
+    <br />
     <SlRelativeTime date="2020-07-15T09:17:00-04:00" format="long" />
   </>
 );
@@ -81,10 +75,10 @@ const App = () => (
 Use the `lang` attribute to set the desired locale.
 
 ```html preview
-English: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="en-US"></sl-relative-time><br>
-Chinese: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="zh-CN"></sl-relative-time><br>
-German: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="de"></sl-relative-time><br>
-Greek: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="el"></sl-relative-time><br>
+English: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="en-US"></sl-relative-time><br />
+Chinese: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="zh-CN"></sl-relative-time><br />
+German: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="de"></sl-relative-time><br />
+Greek: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="el"></sl-relative-time><br />
 Russian: <sl-relative-time date="2020-07-15T09:17:00-04:00" lang="ru"></sl-relative-time>
 ```
 
@@ -93,10 +87,14 @@ import { SlRelativeTime } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    English: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="en-US" /><br />
-    Chinese: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="zh-CN" /><br />
-    German: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="de" /><br />
-    Greek: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="el" /><br />
+    English: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="en-US" />
+    <br />
+    Chinese: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="zh-CN" />
+    <br />
+    German: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="de" />
+    <br />
+    Greek: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="el" />
+    <br />
     Russian: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="ru" />
   </>
 );

docs/components/resize-observer.md

@@ -2,16 +2,12 @@
 
 [component-header:sl-resize-observer]
 
-The Resize Observer component offers a thin, declarative interface to the [`ResizeObserver API`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver).
-
 The resize observer will report changes to the dimensions of the elements it wraps through the `sl-resize` event. When emitted, a collection of [`ResizeObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry) objects will be attached to `event.detail` that contains the target element and information about its dimensions.
 
 ```html preview
 <div class="resize-observer-overview">
   <sl-resize-observer>
-    <div>
-      Resize this box and watch the console 👉
-    </div>
+    <div>Resize this box and watch the console 👉</div>
   </sl-resize-observer>
 </div>
 
@@ -26,9 +22,9 @@ The resize observer will report changes to the dimensions of the elements it wra
 
 <style>
   .resize-observer-overview div {
-    display: flex; 
-    border: solid 2px var(--sl-input-border-color); 
-    align-items: center; 
+    display: flex;
+    border: solid 2px var(--sl-input-border-color);
+    align-items: center;
     justify-content: center;
     text-align: center;
     padding: 4rem 2rem;
@@ -54,9 +50,7 @@ const App = () => (
   <>
     <div className="resize-observer-overview">
       <SlResizeObserver onSlResize={event => console.log(event.detail)}>
-        <div>
-          Resize this box and watch the console 👉
-        </div>
+        <div>Resize this box and watch the console 👉</div>
       </SlResizeObserver>
     </div>
 

docs/components/responsive-media.md

@@ -1,73 +0,0 @@
-# Responsive Media
-
-[component-header:sl-responsive-media]
-
-Displays media in the desired aspect ratio.
-
-You can slot in any [replaced element](https://developer.mozilla.org/en-US/docs/Web/CSS/Replaced_element), including `<iframe>`, `<img>`, and `<video>`. As the element's width changes, its height will resize proportionally. Only one element should be slotted into the container. The default aspect ratio is `16:9`.
-
-```html preview
-<sl-responsive-media>
-  <img src="https://images.unsplash.com/photo-1541427468627-a89a96e5ca1d?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1800&q=80" alt="A train riding through autumn foliage with mountains in the distance.">
-</sl-responsive-media>
-```
-
-```jsx react
-import { SlResponsiveMedia } from '@shoelace-style/shoelace/dist/react';
-
-const App = () => (
-  <SlResponsiveMedia>
-    <img 
-      src="https://images.unsplash.com/photo-1541427468627-a89a96e5ca1d?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1800&q=80"
-      alt="A train riding through autumn foliage with mountains in the distance."
-    />
-  </SlResponsiveMedia>
-);
-```
-
-## Examples
-
-### Responsive Images
-
-The following image maintains a `4:3` aspect ratio as its container is resized.
-
-```html preview
-<sl-responsive-media aspect-ratio="4:3">
-  <img src="https://images.unsplash.com/photo-1473186578172-c141e6798cf4?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1800&q=80" alt="Two blue chairs on a sandy beach.">
-</sl-responsive-media>
-```
-
-```jsx react
-import { SlResponsiveMedia } from '@shoelace-style/shoelace/dist/react';
-
-const App = () => (
-  <SlResponsiveMedia aspect-ratio="4:3">
-    <img 
-      src="https://images.unsplash.com/photo-1473186578172-c141e6798cf4?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1800&q=80" 
-      alt="Two blue chairs on a sandy beach."
-    />
-  </SlResponsiveMedia>
-);
-```
-
-### Responsive Videos
-
-The following video is embedded using an `iframe` and maintains a `16:9` aspect ratio as its container is resized.
-
-```html preview
-<sl-responsive-media aspect-ratio="16:9">
-  <iframe src="https://player.vimeo.com/video/1053647?title=0&byline=0&portrait=0" frameborder="0" allow="autoplay; fullscreen" allowfullscreen></iframe>
-</sl-responsive-media>
-```
-
-```jsx react
-import { SlResponsiveMedia } from '@shoelace-style/shoelace/dist/react';
-
-const App = () => (
-  <SlResponsiveMedia aspect-ratio="16:9">
-    <iframe src="https://player.vimeo.com/video/1053647?title=0&byline=0&portrait=0" frameborder="0" allow="autoplay; fullscreen" allowfullscreen />
-  </SlResponsiveMedia>
-);
-```
-
-[component-metadata:sl-responsive-media]

docs/components/select.md

@@ -2,84 +2,128 @@
 
 [component-header:sl-select]
 
-Selects allow you to choose one or more items from a dropdown menu.
-
 ```html preview
 <sl-select>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
-  <sl-divider></sl-divider>
-  <sl-menu-item value="option-4">Option 4</sl-menu-item>
-  <sl-menu-item value="option-5">Option 5</sl-menu-item>
-  <sl-menu-item value="option-6">Option 6</sl-menu-item>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
+  <sl-option value="option-4">Option 4</sl-option>
+  <sl-option value="option-5">Option 5</sl-option>
+  <sl-option value="option-6">Option 6</sl-option>
 </sl-select>
 ```
 
 ```jsx react
-import { SlDivider, SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect>
-    <SlMenuItem value="option-1">Option 1</SlMenuItem>
-    <SlMenuItem value="option-2">Option 2</SlMenuItem>
-    <SlMenuItem value="option-3">Option 3</SlMenuItem>
-    <SlDivider />
-    <SlMenuItem value="option-4">Option 4</SlMenuItem>
-    <SlMenuItem value="option-5">Option 5</SlMenuItem>
-    <SlMenuItem value="option-6">Option 6</SlMenuItem>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
+    <SlOption value="option-4">Option 4</SlOption>
+    <SlOption value="option-5">Option 5</SlOption>
+    <SlOption value="option-6">Option 6</SlOption>
   </SlSelect>
 );
 ```
 
-?> This component doesn't work with standard forms. Use [`<sl-form>`](/components/form) instead.
+?> This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
 
 ## Examples
 
+### Labels
+
+Use the `label` attribute to give the select an accessible label. For labels that contain HTML, use the `label` slot instead.
+
+```html preview
+<sl-select label="Select one">
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
+</sl-select>
+```
+
+```jsx react
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlSelect label="Select one">
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
+  </SlSelect>
+);
+```
+
+### Help Text
+
+Add descriptive help text to a select with the `help-text` attribute. For help texts that contain HTML, use the `help-text` slot instead.
+
+```html preview
+<sl-select label="Experience" help-text="Please tell us your skill level.">
+  <sl-option value="1">Novice</sl-option>
+  <sl-option value="2">Intermediate</sl-option>
+  <sl-option value="3">Advanced</sl-option>
+</sl-select>
+```
+
+```jsx react
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlSelect label="Experience" help-text="Please tell us your skill level.">
+    <SlOption value="1">Novice</SlOption>
+    <SlOption value="2">Intermediate</SlOption>
+    <SlOption value="3">Advanced</SlOption>
+  </SlSelect>
+);
+```
+
 ### Placeholders
 
 Use the `placeholder` attribute to add a placeholder.
 
 ```html preview
 <sl-select placeholder="Select one">
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
 </sl-select>
 ```
 
 ```jsx react
-import { SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect placeholder="Select one">
-    <SlMenuItem value="option-1">Option 1</SlMenuItem>
-    <SlMenuItem value="option-2">Option 2</SlMenuItem>
-    <SlMenuItem value="option-3">Option 3</SlMenuItem>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
   </SlSelect>
 );
 ```
 
 ### Clearable
 
-Use the `clearable` attribute to make the control clearable.
+Use the `clearable` attribute to make the control clearable. The clear button only appears when an option is selected.
 
 ```html preview
-<sl-select placeholder="Clearable" clearable>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+<sl-select clearable value="option-1">
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
 </sl-select>
 ```
 
 ```jsx react
-import { SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect placeholder="Clearable" clearable>
-    <SlMenuItem value="option-1">Option 1</SlMenuItem>
-    <SlMenuItem value="option-2">Option 2</SlMenuItem>
-    <SlMenuItem value="option-3">Option 3</SlMenuItem>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
   </SlSelect>
 );
 ```
@@ -90,20 +134,20 @@ Add the `filled` attribute to draw a filled select.
 
 ```html preview
 <sl-select filled>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
 </sl-select>
 ```
 
 ```jsx react
-import { SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect filled>
-    <SlMenuItem value="option-1">Option 1</SlMenuItem>
-    <SlMenuItem value="option-2">Option 2</SlMenuItem>
-    <SlMenuItem value="option-3">Option 3</SlMenuItem>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
   </SlSelect>
 );
 ```
@@ -114,20 +158,20 @@ Use the `pill` attribute to give selects rounded edges.
 
 ```html preview
 <sl-select pill>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
 </sl-select>
 ```
 
 ```jsx react
-import { SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect pill>
-    <SlMenuItem value="option-1">Option 1</SlMenuItem>
-    <SlMenuItem value="option-2">Option 2</SlMenuItem>
-    <SlMenuItem value="option-3">Option 3</SlMenuItem>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
   </SlSelect>
 );
 ```
@@ -138,317 +182,250 @@ Use the `disabled` attribute to disable a select.
 
 ```html preview
 <sl-select placeholder="Disabled" disabled>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
 </sl-select>
 ```
 
 ```jsx react
-import { SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlSelect placeholder="Disabled" disabled>
-    <SlMenuItem value="option-1">Option 1</SlMenuItem>
-    <SlMenuItem value="option-2">Option 2</SlMenuItem>
-    <SlMenuItem value="option-3">Option 3</SlMenuItem>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
   </SlSelect>
 );
 ```
 
 ### Multiple
 
-To allow multiple options to be selected, use the `multiple` attribute. It's a good practice to use `clearable` when this option is enabled. When using this option, `value` will be an array instead of a string.
+To allow multiple options to be selected, use the `multiple` attribute. It's a good practice to use `clearable` when this option is enabled. To set multiple values at once, set `value` to a space-delimited list of values.
 
 ```html preview
-<sl-select placeholder="Select a few" multiple clearable>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
-  <sl-divider></sl-divider>
-  <sl-menu-item value="option-4">Option 4</sl-menu-item>
-  <sl-menu-item value="option-5">Option 5</sl-menu-item>
-  <sl-menu-item value="option-6">Option 6</sl-menu-item>
+<sl-select label="Select a Few" value="option-1 option-2 option-3" multiple clearable>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
+  <sl-option value="option-4">Option 4</sl-option>
+  <sl-option value="option-5">Option 5</sl-option>
+  <sl-option value="option-6">Option 6</sl-option>
 </sl-select>
 ```
 
 ```jsx react
-import { SlDivider, SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlSelect placeholder="Select a few" multiple clearable>
-    <SlMenuItem value="option-1">Option 1</SlMenuItem>
-    <SlMenuItem value="option-2">Option 2</SlMenuItem>
-    <SlMenuItem value="option-3">Option 3</SlMenuItem>
-    <SlDivider />
-    <SlMenuItem value="option-4">Option 4</SlMenuItem>
-    <SlMenuItem value="option-5">Option 5</SlMenuItem>
-    <SlMenuItem value="option-6">Option 6</SlMenuItem>
+  <SlSelect label="Select a Few" value="option-1 option-2 option-3" multiple clearable>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
+    <SlOption value="option-4">Option 4</SlOption>
+    <SlOption value="option-5">Option 5</SlOption>
+    <SlOption value="option-6">Option 6</SlOption>
+  </SlSelect>
+);
+```
+
+?> Note that multi-select options may wrap, causing the control to expand vertically. You can use the `max-options-visible` attribute to control the maximum number of selected options to show at once.
+
+### Setting Initial Values
+
+Use the `value` attribute to set the initial selection. When using `multiple`, use space-delimited values to select more than one option.
+
+```html preview
+<sl-select value="option-1 option-2" multiple clearable>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
+  <sl-option value="option-4">Option 4</sl-option>
+</sl-select>
+```
+
+```jsx react
+import { SlDivider, SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlSelect value="option-1 option-2" multiple clearable>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
   </SlSelect>
 );
 ```
 
 ### Grouping Options
 
-Options can be grouped visually using menu labels and dividers.
+Use `<sl-divider>` to group listbox items visually. You can also use `<small>` to provide labels, but they won't be announced by most assistive devices.
 
 ```html preview
-<sl-select placeholder="Select one">
-  <sl-menu-label>Group 1</sl-menu-label>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+<sl-select>
+  <small>Section 1</small>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
   <sl-divider></sl-divider>
-  <sl-menu-label>Group 2</sl-menu-label>
-  <sl-menu-item value="option-4">Option 4</sl-menu-item>
-  <sl-menu-item value="option-5">Option 5</sl-menu-item>
-  <sl-menu-item value="option-6">Option 6</sl-menu-item>
+  <small>Section 2</small>
+  <sl-option value="option-4">Option 4</sl-option>
+  <sl-option value="option-5">Option 5</sl-option>
+  <sl-option value="option-6">Option 6</sl-option>
 </sl-select>
 ```
 
 ```jsx react
-import { SlDivider, SlMenuItem, SlMenuLabel, SlSelect } from '@shoelace-style/shoelace/dist/react';
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlSelect placeholder="Select one">
-    <SlMenuLabel>Group 1</SlMenuLabel>
-    <SlMenuItem value="option-1">Option 1</SlMenuItem>
-    <SlMenuItem value="option-2">Option 2</SlMenuItem>
-    <SlMenuItem value="option-3">Option 3</SlMenuItem>
-    <SlDivider></SlDivider>
-    <SlMenuLabel>Group 2</SlMenuLabel>
-    <SlMenuItem value="option-4">Option 4</SlMenuItem>
-    <SlMenuItem value="option-5">Option 5</SlMenuItem>
-    <SlMenuItem value="option-6">Option 6</SlMenuItem>
+  <SlSelect>
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
+    <SlOption value="option-4">Option 4</SlOption>
+    <SlOption value="option-5">Option 5</SlOption>
+    <SlOption value="option-6">Option 6</SlOption>
   </SlSelect>
 );
 ```
 
 ### Sizes
 
-Use the `size` attribute to change a select's size.
+Use the `size` attribute to change a select's size. Note that size does not apply to listbox options.
 
 ```html preview
-<sl-select placeholder="Small" size="small" multiple>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+<sl-select placeholder="Small" size="small">
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
 </sl-select>
 
-<br>
+<br />
 
-<sl-select placeholder="Medium" size="medium" multiple>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+<sl-select placeholder="Medium" size="medium">
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
 </sl-select>
 
-<br>
+<br />
 
-<sl-select placeholder="Large" size="large" multiple>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+<sl-select placeholder="Large" size="large">
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
 </sl-select>
 ```
 
 ```jsx react
-import { SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
+import { SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlSelect placeholder="Small" size="small" multiple>
-      <SlMenuItem value="option-1">Option 1</SlMenuItem>
-      <SlMenuItem value="option-2">Option 2</SlMenuItem>
-      <SlMenuItem value="option-3">Option 3</SlMenuItem>
+    <SlSelect placeholder="Small" size="small">
+      <SlOption value="option-1">Option 1</SlOption>
+      <SlOption value="option-2">Option 2</SlOption>
+      <SlOption value="option-3">Option 3</SlOption>
     </SlSelect>
 
     <br />
 
-    <SlSelect placeholder="Medium" size="medium" multiple>
-      <SlMenuItem value="option-1">Option 1</SlMenuItem>
-      <SlMenuItem value="option-2">Option 2</SlMenuItem>
-      <SlMenuItem value="option-3">Option 3</SlMenuItem>
+    <SlSelect placeholder="Medium" size="medium">
+      <SlOption value="option-1">Option 1</SlOption>
+      <SlOption value="option-2">Option 2</SlOption>
+      <SlOption value="option-3">Option 3</SlOption>
     </SlSelect>
 
     <br />
 
-    <SlSelect placeholder="Large" size="large" multiple>
-      <SlMenuItem value="option-1">Option 1</SlMenuItem>
-      <SlMenuItem value="option-2">Option 2</SlMenuItem>
-      <SlMenuItem value="option-3">Option 3</SlMenuItem>
+    <SlSelect placeholder="Large" size="large">
+      <SlOption value="option-1">Option 1</SlOption>
+      <SlOption value="option-2">Option 2</SlOption>
+      <SlOption value="option-3">Option 3</SlOption>
     </SlSelect>
   </>
 );
 ```
 
-### Selecting Options Programmatically
+### Placement
 
-The `value` property is bound to the current selection. As the selection changes, so will the value. To programmatically manage the selection, update the `value` property.
+The preferred placement of the select's listbox can be set with the `placement` attribute. Note that the actual position may vary to ensure the panel remains in the viewport. Valid placements are `top` and `bottom`.
 
 ```html preview
-<div class="selecting-example">
-  <sl-select>
-    <sl-menu-item value="option-1">Option 1</sl-menu-item>
-    <sl-menu-item value="option-2">Option 2</sl-menu-item>
-    <sl-menu-item value="option-3">Option 3</sl-menu-item>
-  </sl-select>
-
-  <br>
-
-  <sl-button data-option="option-1">Set 1</sl-button>
-  <sl-button data-option="option-2">Set 2</sl-button>
-  <sl-button data-option="option-3">Set 3</sl-button>
-</div>
-
-<script>
-  const container = document.querySelector('.selecting-example');
-  const select = container.querySelector('sl-select');
-
-  [...container.querySelectorAll('sl-button')].map(button => {
-    button.addEventListener('click', () => {
-      select.value = button.dataset.option; 
-    });
-  });
-</script>
-```
-
-```jsx react
-import { useState } from 'react';
-import { SlButton, SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
-
-const App = () => {
-  const [value, setValue] = useState('option-1');
-
-  return (
-    <>
-      <SlSelect value={value} onSlChange={event => setValue(event.target.value)}>
-        <SlMenuItem value="option-1">Option 1</SlMenuItem>
-        <SlMenuItem value="option-2">Option 2</SlMenuItem>
-        <SlMenuItem value="option-3">Option 3</SlMenuItem>
-      </SlSelect>
-
-      <br />
-
-      <SlButton onClick={() => setValue('option-1')}>Set 1</SlButton>
-      <SlButton onClick={() => setValue('option-2')}>Set 2</SlButton>
-      <SlButton onClick={() => setValue('option-3')}>Set 3</SlButton>
-    </>
-  );
-};
-```
-
-### Labels
-
-Use the `label` attribute to give the select an accessible label. For labels that contain HTML, use the `label` slot instead.
-
-```html preview
-<sl-select label="Select one">
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
+<sl-select placement="top">
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
 </sl-select>
 ```
 
 ```jsx react
-import { SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
+import {
+  SlOption,
+  SlSelect
+} from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlSelect label="Select one">
-    <SlMenuItem value="option-1">Option 1</SlMenuItem>
-    <SlMenuItem value="option-2">Option 2</SlMenuItem>
-    <SlMenuItem value="option-3">Option 3</SlMenuItem>
-  </SlSelect>
+  <SlSelect placement="top">
+    <SlOption value="option-1">Option 1</SlOption>
+    <SlOption value="option-2">Option 2</SlOption>
+    <SlOption value="option-3">Option 3</SlOption>
+  </SlDropdown>
 );
 ```
 
-### Help Text
+### Prefix Icons
 
-Add descriptive help text to a select with the `help-text` attribute. For help texts that contain HTML, use the `help-text` slot instead.
+Use the `prefix` slot to prepend an icon to the control.
 
 ```html preview
-<sl-select 
-  label="Experience" 
-  help-text="Please tell us your skill level."
->
-  <sl-menu-item value="1">Novice</sl-menu-item>
-  <sl-menu-item value="2">Intermediate</sl-menu-item>
-  <sl-menu-item value="3">Advanced</sl-menu-item>
+<sl-select placeholder="Small" size="small" clearable>
+  <sl-icon name="house" slot="prefix"></sl-icon>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
+</sl-select>
+<br />
+<sl-select placeholder="Medium" size="medium" clearable>
+  <sl-icon name="house" slot="prefix"></sl-icon>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
+</sl-select>
+<br />
+<sl-select placeholder="Large" size="large" clearable>
+  <sl-icon name="house" slot="prefix"></sl-icon>
+  <sl-option value="option-1">Option 1</sl-option>
+  <sl-option value="option-2">Option 2</sl-option>
+  <sl-option value="option-3">Option 3</sl-option>
 </sl-select>
 ```
 
 ```jsx react
-import { SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
-
-const App = () => (
-  <SlSelect 
-    label="Experience"
-    help-text="Please tell us your skill level."
-  >
-    <SlMenuItem value="1">Novice</SlMenuItem>
-    <SlMenuItem value="2">Intermediate</SlMenuItem>
-    <SlMenuItem value="3">Advanced</SlMenuItem>
-  </SlSelect>
-);
-```
-
-### Prefix & Suffix Icons
-
-Use the `prefix` and `suffix` slots to add icons.
-
-```html preview
-<sl-select placeholder="Small" size="small">
-  <sl-icon name="house" slot="prefix"></sl-icon>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
-  <sl-icon name="chat" slot="suffix"></sl-icon>
-</sl-select>
-<br>
-<sl-select placeholder="Medium" size="medium">
-  <sl-icon name="house" slot="prefix"></sl-icon>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
-  <sl-icon name="chat" slot="suffix"></sl-icon>
-</sl-select>
-<br>
-<sl-select placeholder="Large" size="large">
-  <sl-icon name="house" slot="prefix"></sl-icon>
-  <sl-menu-item value="option-1">Option 1</sl-menu-item>
-  <sl-menu-item value="option-2">Option 2</sl-menu-item>
-  <sl-menu-item value="option-3">Option 3</sl-menu-item>
-  <sl-icon name="chat" slot="suffix"></sl-icon>
-</sl-select>
-```
-
-```jsx react
-import { SlIcon, SlMenuItem, SlSelect } from '@shoelace-style/shoelace/dist/react';
+import { SlIcon, SlOption, SlSelect } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
     <SlSelect placeholder="Small" size="small">
       <SlIcon name="house" slot="prefix"></SlIcon>
-      <SlMenuItem value="option-1">Option 1</SlMenuItem>
-      <SlMenuItem value="option-2">Option 2</SlMenuItem>
-      <SlMenuItem value="option-3">Option 3</SlMenuItem>
-      <SlIcon name="chat" slot="suffix"></SlIcon>
+      <SlOption value="option-1">Option 1</SlOption>
+      <SlOption value="option-2">Option 2</SlOption>
+      <SlOption value="option-3">Option 3</SlOption>
     </SlSelect>
     <br />
     <SlSelect placeholder="Medium" size="medium">
       <SlIcon name="house" slot="prefix"></SlIcon>
-      <SlMenuItem value="option-1">Option 1</SlMenuItem>
-      <SlMenuItem value="option-2">Option 2</SlMenuItem>
-      <SlMenuItem value="option-3">Option 3</SlMenuItem>
-      <SlIcon name="chat" slot="suffix"></SlIcon>
+      <SlOption value="option-1">Option 1</SlOption>
+      <SlOption value="option-2">Option 2</SlOption>
+      <SlOption value="option-3">Option 3</SlOption>
     </SlSelect>
     <br />
     <SlSelect placeholder="Large" size="large">
       <SlIcon name="house" slot="prefix"></SlIcon>
-      <SlMenuItem value="option-1">Option 1</SlMenuItem>
-      <SlMenuItem value="option-2">Option 2</SlMenuItem>
-      <SlMenuItem value="option-3">Option 3</SlMenuItem>
-      <SlIcon name="chat" slot="suffix"></SlIcon>
+      <SlOption value="option-1">Option 1</SlOption>
+      <SlOption value="option-2">Option 2</SlOption>
+      <SlOption value="option-3">Option 3</SlOption>
     </SlSelect>
   </>
 );

docs/components/skeleton.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-skeleton]
 
-Skeletons are used to show where content will eventually be drawn.
-
 These are simple containers for scaffolding layouts that mimic what users will see when content has finished loading. This prevents large areas of empty space during asynchronous operations.
 
 Skeletons try not to be opinionated, as there are endless possibilities for designing layouts. Therefore, you'll likely use more than one skeleton to create the effect you want. If you find yourself using them frequently, consider creating a template that renders them with the desired arrangement and styles.
@@ -101,7 +99,7 @@ const App = () => (
       <SlSkeleton />
       <SlSkeleton />
       <SlSkeleton />
-    </div>  
+    </div>
 
     <style>{css}</style>
   </>
@@ -112,7 +110,7 @@ const App = () => (
 
 ### Effects
 
-There are two built-in effects, `sheen` and `pulse`. Effects are intentionally subtle, as they can be distracting when used extensively. The default is `none`, which displays a static, non-animated skeleton. 
+There are two built-in effects, `sheen` and `pulse`. Effects are intentionally subtle, as they can be distracting when used extensively. The default is `none`, which displays a static, non-animated skeleton.
 
 ```html preview
 <div class="skeleton-effects">
@@ -155,10 +153,8 @@ const App = () => (
     <div className="skeleton-effects">
       <SlSkeleton effect="none" />
       None
-
       <SlSkeleton effect="sheen" />
       Sheen
-
       <SlSkeleton effect="pulse" />
       Pulse
     </div>
@@ -252,13 +248,13 @@ Set a matching width and height to make a circle, square, or rounded avatar skel
     display: inline-block;
     width: 3rem;
     height: 3rem;
-    margin-right: .5rem;
+    margin-right: 0.5rem;
   }
 
   .skeleton-avatars sl-skeleton:nth-child(1) {
     --border-radius: 0;
   }
-  
+
   .skeleton-avatars sl-skeleton:nth-child(2) {
     --border-radius: var(--sl-border-radius-medium);
   }
@@ -333,7 +329,20 @@ Use the `--border-radius` custom property to make circles, squares, and rectangl
 
   .skeleton-shapes .cross::part(indicator) {
     --border-radius: 0;
-    clip-path: polygon(20% 0%, 0% 20%, 30% 50%, 0% 80%, 20% 100%, 50% 70%, 80% 100%, 100% 80%, 70% 50%, 100% 20%, 80% 0%, 50% 30%);
+    clip-path: polygon(
+      20% 0%,
+      0% 20%,
+      30% 50%,
+      0% 80%,
+      20% 100%,
+      50% 70%,
+      80% 100%,
+      100% 80%,
+      70% 50%,
+      100% 20%,
+      80% 0%,
+      50% 30%
+    );
   }
 
   .skeleton-shapes .comment::part(indicator) {
@@ -342,7 +351,7 @@ Use the `--border-radius` custom property to make circles, squares, and rectangl
   }
 
   .skeleton-shapes sl-skeleton:not(:last-child) {
-    margin-right: .5rem;
+    margin-right: 0.5rem;
   }
 </style>
 ```
@@ -387,13 +396,13 @@ const css = `
 
 const App = () => (
   <>
-  <div className="skeleton-shapes">
-    <SlSkeleton className="square" />
-    <SlSkeleton className="circle" />
-    <SlSkeleton className="triangle" />
-    <SlSkeleton className="cross" />
-    <SlSkeleton className="comment" />
-  </div>
+    <div className="skeleton-shapes">
+      <SlSkeleton className="square" />
+      <SlSkeleton className="circle" />
+      <SlSkeleton className="triangle" />
+      <SlSkeleton className="cross" />
+      <SlSkeleton className="comment" />
+    </div>
 
     <style>{css}</style>
   </>
@@ -428,12 +437,7 @@ const css = `
   }
 `;
 
-const App = () => (
-  <SlSkeleton 
-    effect="sheen" 
-    style={{ '--color': 'tomato', '--sheen-color': '#ffb094' }} 
-  />
-);
+const App = () => <SlSkeleton effect="sheen" style={{ '--color': 'tomato', '--sheen-color': '#ffb094' }} />;
 ```
 
 [component-metadata:sl-skeleton]

docs/components/spinner.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-spinner]
 
-Spinners are used to show the progress of an indeterminate operation.
-
 ```html preview
 <sl-spinner></sl-spinner>
 ```
@@ -11,9 +9,7 @@ Spinners are used to show the progress of an indeterminate operation.
 ```jsx react
 import { SlSpinner } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlSpinner />
-);
+const App = () => <SlSpinner />;
 ```
 
 ## Examples
@@ -45,18 +41,18 @@ const App = () => (
 The width of the spinner's track can be changed by setting the `--track-width` custom property.
 
 ```html preview
-<sl-spinner style="font-size: 3rem; --track-width: 6px;"></sl-spinner>
+<sl-spinner style="font-size: 50px; --track-width: 10px;"></sl-spinner>
 ```
 
 ```jsx react
 import { SlSpinner } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlSpinner 
+  <SlSpinner
     style={{
       fontSize: '3rem',
       '--track-width': '6px'
-    }} 
+    }}
   />
 );
 ```
@@ -73,12 +69,12 @@ The spinner's colors can be changed by setting the `--indicator-color` and `--tr
 import { SlSpinner } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlSpinner 
+  <SlSpinner
     style={{
       fontSize: '3rem',
       '--indicator-color': 'deeppink',
       '--track-color': 'pink'
-    }} 
+    }}
   />
 );
 ```

docs/components/split-panel.md

@@ -2,51 +2,187 @@
 
 [component-header:sl-split-panel]
 
-Split panels display two adjacent panels, allowing the user to reposition them.
-
 ```html preview
 <sl-split-panel>
-  <div slot="start" style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;">
+  <div
+    slot="start"
+    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
+  >
     Start
   </div>
-  <div slot="end" style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;">
+  <div
+    slot="end"
+    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
+  >
     End
   </div>
 </sl-split-panel>
 ```
 
+```jsx react
+import { SlSplitPanel } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlSplitPanel>
+    <div
+      slot="start"
+      style={{
+        height: '200px',
+        background: 'var(--sl-color-neutral-50)',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center'
+      }}
+    >
+      Start
+    </div>
+    <div
+      slot="end"
+      style={{
+        height: '200px',
+        background: 'var(--sl-color-neutral-50)',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center'
+      }}
+    >
+      End
+    </div>
+  </SlSplitPanel>
+);
+```
+
 ## Examples
 
 ### Initial Position
 
-To set the initial position in pixels, use the `position` attribute. If you need to set the initial value as a percentage, use the `setPositionAsPercentage()` method instead. If no position is provided, it will default to half of the available space.
+To set the initial position, use the `position` attribute. If no position is provided, it will default to 50% of the available space.
 
 ```html preview
-<sl-split-panel position="200">
-  <div slot="start" style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;">
+<sl-split-panel position="75">
+  <div
+    slot="start"
+    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
+  >
     Start
   </div>
-  <div slot="end" style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;">
+  <div
+    slot="end"
+    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
+  >
     End
   </div>
 </sl-split-panel>
 ```
 
+### Initial Position in Pixels
+
+To set the initial position in pixels instead of a percentage, use the `position-in-pixels` attribute.
+
+```html preview
+<sl-split-panel position-in-pixels="150">
+  <div
+    slot="start"
+    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
+  >
+    Start
+  </div>
+  <div
+    slot="end"
+    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
+  >
+    End
+  </div>
+</sl-split-panel>
+```
+
+```jsx react
+import { SlSplitPanel } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlSplitPanel position="200">
+    <div
+      slot="start"
+      style={{
+        height: '200px',
+        background: 'var(--sl-color-neutral-50)',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center'
+      }}
+    >
+      Start
+    </div>
+    <div
+      slot="end"
+      style={{
+        height: '200px',
+        background: 'var(--sl-color-neutral-50)',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center'
+      }}
+    >
+      End
+    </div>
+  </SlSplitPanel>
+);
+```
+
 ### Vertical
 
 Add the `vertical` attribute to render the split panel in a vertical orientation where the start and end panels are stacked. You also need to set a height when using the vertical orientation.
 
 ```html preview
 <sl-split-panel vertical style="height: 400px;">
-  <div slot="start" style="height: 100%; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;">
+  <div
+    slot="start"
+    style="height: 100%; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
+  >
     Start
   </div>
-  <div slot="end" style="height: 100%; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;">
+  <div
+    slot="end"
+    style="height: 100%; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
+  >
     End
   </div>
 </sl-split-panel>
 ```
 
+```jsx react
+import { SlSplitPanel } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlSplitPanel vertical style={{ height: '400px' }}>
+    <div
+      slot="start"
+      style={{
+        height: '100%',
+        background: 'var(--sl-color-neutral-50)',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center'
+      }}
+    >
+      Start
+    </div>
+    <div
+      slot="end"
+      style={{
+        height: '100%',
+        background: 'var(--sl-color-neutral-50)',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center'
+      }}
+    >
+      End
+    </div>
+  </SlSplitPanel>
+);
+```
+
 ### Snapping
 
 To snap panels at specific positions while dragging, add the `snap` attribute with one or more space-separated values. Values must be in pixels or percentages. For example, to snap the panel at `100px` and `50%`, use `snap="100px 50%"`. You can also customize how close the divider must be before snapping with the `snap-threshold` attribute.
@@ -54,10 +190,16 @@ To snap panels at specific positions while dragging, add the `snap` attribute wi
 ```html preview
 <div class="split-panel-snapping">
   <sl-split-panel snap="100px 50%">
-    <div slot="start" style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;">
+    <div
+      slot="start"
+      style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
+    >
       Start
     </div>
-    <div slot="end" style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;">
+    <div
+      slot="end"
+      style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
+    >
       End
     </div>
   </sl-split-panel>
@@ -92,21 +234,127 @@ To snap panels at specific positions while dragging, add the `snap` attribute wi
 </style>
 ```
 
+```jsx react
+import { SlSplitPanel } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .split-panel-snapping {
+    position: relative;
+  }
+
+  .split-panel-snapping-dots::before,
+  .split-panel-snapping-dots::after {
+    content: '';
+    position: absolute;
+    bottom: -12px;
+    width: 6px;
+    height: 6px;
+    border-radius: 50%;
+    background: var(--sl-color-neutral-400);
+    transform: translateX(-3px);
+  }
+
+  .split-panel-snapping-dots::before {
+    left: 100px;
+  }
+
+  .split-panel-snapping-dots::after {
+    left: 50%;
+  }
+`;
+
+const App = () => (
+  <>
+    <div className="split-panel-snapping">
+      <SlSplitPanel snap="100px 50%">
+        <div
+          slot="start"
+          style={{
+            height: '200px',
+            background: 'var(--sl-color-neutral-50)',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center'
+          }}
+        >
+          Start
+        </div>
+        <div
+          slot="end"
+          style={{
+            height: '200px',
+            background: 'var(--sl-color-neutral-50)',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center'
+          }}
+        >
+          End
+        </div>
+      </SlSplitPanel>
+
+      <div className="split-panel-snapping-dots" />
+    </div>
+
+    <style>{css}</style>
+  </>
+);
+```
+
 ### Disabled
 
-Add the `disabled` attribute to prevent the split panel from being repositioned.
+Add the `disabled` attribute to prevent the divider from being repositioned.
 
 ```html preview
 <sl-split-panel disabled>
-  <div slot="start" style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;">
+  <div
+    slot="start"
+    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
+  >
     Start
   </div>
-  <div slot="end" style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;">
+  <div
+    slot="end"
+    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
+  >
     End
   </div>
 </sl-split-panel>
 ```
 
+```jsx react
+import { SlSplitPanel } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlSplitPanel disabled>
+    <div
+      slot="start"
+      style={{
+        height: '200px',
+        background: 'var(--sl-color-neutral-50)',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center'
+      }}
+    >
+      Start
+    </div>
+    <div
+      slot="end"
+      style={{
+        height: '200px',
+        background: 'var(--sl-color-neutral-50)',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center'
+      }}
+    >
+      End
+    </div>
+  </SlSplitPanel>
+);
+```
+
 ### Setting the Primary Panel
 
 By default, both panels will grow or shrink proportionally when the host element is resized. If a primary panel is designated, it will maintain its size and the secondary panel will grow or shrink to fit the remaining space. You can set the primary panel to `start` or `end` using the `primary` attribute.
@@ -116,18 +364,24 @@ Try resizing the example below with each option and notice how the panels respon
 ```html preview
 <div class="split-panel-primary">
   <sl-split-panel>
-    <div slot="start" style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;">
+    <div
+      slot="start"
+      style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
+    >
       Start
     </div>
-    <div slot="end" style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;">
+    <div
+      slot="end"
+      style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
+    >
       End
     </div>
   </sl-split-panel>
 
   <sl-select label="Primary Panel" value="" style="max-width: 200px; margin-top: 1rem;">
-    <sl-menu-item value="">None</sl-menu-item>
-    <sl-menu-item value="start">Start</sl-menu-item>
-    <sl-menu-item value="end">End</sl-menu-item>
+    <sl-option value="">None</sl-option>
+    <sl-option value="start">Start</sl-option>
+    <sl-option value="end">End</sl-option>
   </sl-select>
 </div>
 
@@ -136,92 +390,315 @@ Try resizing the example below with each option and notice how the panels respon
   const splitPanel = container.querySelector('sl-split-panel');
   const select = container.querySelector('sl-select');
 
-  select.addEventListener('sl-change', () => splitPanel.primary = select.value);
+  select.addEventListener('sl-change', () => (splitPanel.primary = select.value));
 </script>
 ```
 
+```jsx react
+import { useState } from 'react';
+import { SlSplitPanel, SlSelect, SlMenuItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [primary, setPrimary] = useState('');
+
+  return (
+    <>
+      <SlSplitPanel primary={primary}>
+        <div
+          slot="start"
+          style={{
+            height: '200px',
+            background: 'var(--sl-color-neutral-50)',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center'
+          }}
+        >
+          Start
+        </div>
+        <div
+          slot="end"
+          style={{
+            height: '200px',
+            background: 'var(--sl-color-neutral-50)',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center'
+          }}
+        >
+          End
+        </div>
+      </SlSplitPanel>
+
+      <SlSelect
+        label="Primary Panel"
+        value={primary}
+        style={{ maxWidth: '200px', marginTop: '1rem' }}
+        onSlChange={event => setPrimary(event.target.value)}
+      >
+        <SlMenuItem value="">None</SlMenuItem>
+        <SlMenuItem value="start">Start</SlMenuItem>
+        <SlMenuItem value="end">End</SlMenuItem>
+      </SlSelect>
+    </>
+  );
+};
+```
+
 ### Min & Max
 
-To set a minimum or maximum size of the primary panel, use the `--min` and `--max` custom properties. Since the secondary panel is flexible, size constraints can only be applied to the primary panel (or the `start` panel if a primary panel isn't designated).
+To set a minimum or maximum size of the primary panel, use the `--min` and `--max` custom properties. Since the secondary panel is flexible, size constraints can only be applied to the primary panel. If no primary panel is designated, these constraints will be applied to the `start` panel.
 
-This examples demonstrates how you can make both panels be a minimum of 150px using `--min`, `--max`, and the `calc()` function.
+This examples demonstrates how you can ensure both panels are at least 150px using `--min`, `--max`, and the `calc()` function.
 
 ```html preview
 <sl-split-panel style="--min: 150px; --max: calc(100% - 150px);">
-  <div slot="start" style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;">
+  <div
+    slot="start"
+    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
+  >
     Start
   </div>
-  <div slot="end" style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;">
+  <div
+    slot="end"
+    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
+  >
     End
   </div>
 </sl-split-panel>
 ```
 
+```jsx react
+import { SlSplitPanel } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlSplitPanel style={{ '--min': '150px', '--max': 'calc(100% - 150px)' }}>
+    <div
+      slot="start"
+      style={{
+        height: '200px',
+        background: 'var(--sl-color-neutral-50)',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center'
+      }}
+    >
+      Start
+    </div>
+    <div
+      slot="end"
+      style={{
+        height: '200px',
+        background: 'var(--sl-color-neutral-50)',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center'
+      }}
+    >
+      End
+    </div>
+  </SlSplitPanel>
+);
+```
+
 ### Nested Split Panels
 
 Create complex layouts that can be repositioned independently by nesting split panels.
 
 ```html preview
 <sl-split-panel>
-  <div slot="start" style="height: 400px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;">
+  <div
+    slot="start"
+    style="height: 400px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
+  >
     Start
   </div>
   <div slot="end">
     <sl-split-panel vertical style="height: 400px;">
-      <div slot="start" style="height: 100%; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;">
+      <div
+        slot="start"
+        style="height: 100%; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
+      >
         Top
       </div>
-      <div slot="end" style="height: 100%; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;">
+      <div
+        slot="end"
+        style="height: 100%; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
+      >
         Bottom
       </div>
-    </sl-split-panel>    
+    </sl-split-panel>
   </div>
 </sl-split-panel>
 ```
 
-### Customizing the Divider
+```jsx react
+import { SlSplitPanel } from '@shoelace-style/shoelace/dist/react';
 
-You can target the `divider` part to apply CSS properties to the divider. To add a handle, slot an icon or another element into the `handle` slot. When customizing the divider, make sure to think about focus styles for keyboard users.
-
-```html preview
-<div class="split-panel-custom-divider">
-  <sl-split-panel style="--divider-width: 20px;">
-    <sl-icon slot="handle" name="grip-vertical"></sl-icon>
-    <div slot="start" style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;">
+const App = () => (
+  <SlSplitPanel>
+    <div
+      slot="start"
+      style={{
+        height: '400px',
+        background: 'var(--sl-color-neutral-50)',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center'
+      }}
+    >
       Start
     </div>
-    <div slot="end" style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;">
+    <div slot="end">
+      <SlSplitPanel vertical style={{ height: '400px' }}>
+        <div
+          slot="start"
+          style={{
+            height: '100%',
+            background: 'var(--sl-color-neutral-50)',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center'
+          }}
+        >
+          Start
+        </div>
+        <div
+          slot="end"
+          style={{
+            height: '100%',
+            background: 'var(--sl-color-neutral-50)',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center'
+          }}
+        >
+          End
+        </div>
+      </SlSplitPanel>
+    </div>
+  </SlSplitPanel>
+);
+```
+
+### Customizing the Divider
+
+You can target the `divider` part to apply CSS properties to the divider. To add a custom handle, slot an icon into the `divider` slot. When customizing the divider, make sure to think about focus styles for keyboard users.
+
+```html preview
+<sl-split-panel style="--divider-width: 20px;">
+  <sl-icon slot="divider" name="grip-vertical"></sl-icon>
+  <div
+    slot="start"
+    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
+  >
+    Start
+  </div>
+  <div
+    slot="end"
+    style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
+  >
+    End
+  </div>
+</sl-split-panel>
+```
+
+```jsx react
+import { SlSplitPanel, SlIcon } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlSplitPanel style={{ '--divider-width': '20px' }}>
+    <SlIcon slot="divider" name="grip-vertical" />
+    <div
+      slot="start"
+      style={{
+        height: '200px',
+        background: 'var(--sl-color-neutral-50)',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center'
+      }}
+    >
+      Start
+    </div>
+    <div
+      slot="end"
+      style={{
+        height: '200px',
+        background: 'var(--sl-color-neutral-50)',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center'
+      }}
+    >
       End
     </div>
-  </sl-split-panel>
-</div>
+  </SlSplitPanel>
+);
 ```
 
 Here's a more elaborate example that changes the divider's color and width and adds a styled handle.
 
 ```html preview
-<div class="split-panel-handle">
+<div class="split-panel-divider">
   <sl-split-panel>
-    <sl-icon slot="handle" name="grip-vertical"></sl-icon>
-    <div slot="start" style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;">
+    <sl-icon slot="divider" name="grip-vertical"></sl-icon>
+    <div
+      slot="start"
+      style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
+    >
       Start
     </div>
-    <div slot="end" style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;">
+    <div
+      slot="end"
+      style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;"
+    >
       End
     </div>
   </sl-split-panel>
 </div>
 
 <style>
-  .split-panel-handle sl-split-panel {
+  .split-panel-divider sl-split-panel {
     --divider-width: 2px;
   }
 
-  .split-panel-handle sl-split-panel::part(divider) {
+  .split-panel-divider sl-split-panel::part(divider) {
     background-color: var(--sl-color-pink-600);
   }
 
-  .split-panel-handle sl-icon {
+  .split-panel-divider sl-icon {
+    position: absolute;
+    border-radius: var(--sl-border-radius-small);
+    background: var(--sl-color-pink-600);
+    color: var(--sl-color-neutral-0);
+    padding: 0.5rem 0.125rem;
+  }
+
+  .split-panel-divider sl-split-panel::part(divider):focus-visible {
+    background-color: var(--sl-color-primary-600);
+  }
+
+  .split-panel-divider sl-split-panel:focus-within sl-icon {
+    background-color: var(--sl-color-primary-600);
+    color: var(--sl-color-neutral-0);
+  }
+</style>
+```
+
+```jsx react
+import { SlSplitPanel, SlIcon } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .split-panel-divider sl-split-panel {
+    --divider-width: 2px;
+  }
+
+  .split-panel-divider sl-split-panel::part(divider) {
+    background-color: var(--sl-color-pink-600);
+  }
+
+  .split-panel-divider sl-icon {
     position: absolute;
     border-radius: var(--sl-border-radius-small);
     background: var(--sl-color-pink-600);
@@ -229,15 +706,51 @@ Here's a more elaborate example that changes the divider's color and width and a
     padding: .5rem .125rem;
   }
 
-  .split-panel-handle sl-split-panel::part(divider):focus-visible {
+  .split-panel-divider sl-split-panel::part(divider):focus-visible {
     background-color: var(--sl-color-primary-600);
   }
 
-  .split-panel-handle sl-split-panel:focus-within sl-icon {
+  .split-panel-divider sl-split-panel:focus-within sl-icon {
     background-color: var(--sl-color-primary-600);
     color: var(--sl-color-neutral-0);
   }
-</style>
+`;
+
+const App = () => (
+  <>
+    <div className="split-panel-divider">
+      <SlSplitPanel>
+        <SlIcon slot="divider" name="grip-vertical" />
+        <div
+          slot="start"
+          style={{
+            height: '200px',
+            background: 'var(--sl-color-neutral-50)',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center'
+          }}
+        >
+          Start
+        </div>
+        <div
+          slot="end"
+          style={{
+            height: '200px',
+            background: 'var(--sl-color-neutral-50)',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center'
+          }}
+        >
+          End
+        </div>
+      </SlSplitPanel>
+    </div>
+
+    <style>{css}</style>
+  </>
+);
 ```
 
 [component-metadata:sl-split-panel]

docs/components/switch.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-switch]
 
-Switches allow the user to toggle an option on or off. 
-
 ```html preview
 <sl-switch>Switch</sl-switch>
 ```
@@ -11,12 +9,10 @@ Switches allow the user to toggle an option on or off.
 ```jsx react
 import { SlSwitch } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlSwitch>Switch</SlSwitch>
-);
+const App = () => <SlSwitch>Switch</SlSwitch>;
 ```
 
-?> This component doesn't work with standard forms. Use [`<sl-form>`](/components/form) instead.
+?> This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
 
 ## Examples
 
@@ -31,9 +27,7 @@ Use the `checked` attribute to activate the switch.
 ```jsx react
 import { SlSwitch } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlSwitch checked>Checked</SlSwitch>
-);
+const App = () => <SlSwitch checked>Checked</SlSwitch>;
 ```
 
 ### Disabled
@@ -47,29 +41,53 @@ Use the `disabled` attribute to disable the switch.
 ```jsx react
 import { SlSwitch } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlSwitch disabled>Disabled</SlSwitch>
-);
+const App = () => <SlSwitch disabled>Disabled</SlSwitch>;
 ```
 
-### Custom Size
+## Sizes
 
-Use the available custom properties to make the switch a different size.
+Use the `size` attribute to change a switch's size.
 
 ```html preview
-<sl-switch style="--width: 80px; --height: 32px; --thumb-size: 26px;"></sl-switch>
+<sl-switch size="small">Small</sl-switch>
+<br />
+<sl-switch size="medium">Medium</sl-switch>
+<br />
+<sl-switch size="large">Large</sl-switch>
 ```
 
 ```jsx react
 import { SlSwitch } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlSwitch 
+  <>
+    <SlSwitch size="small">Small</SlSwitch>
+    <br />
+    <SlSwitch size="medium">Medium</SlSwitch>
+    <br />
+    <SlSwitch size="large">Large</SlSwitch>
+  </>
+);
+```
+
+### Custom Styles
+
+Use the available custom properties to change how the switch is styled.
+
+```html preview
+<sl-switch style="--width: 80px; --height: 40px; --thumb-size: 36px;">Really big</sl-switch>
+```
+
+```jsx react
+import { SlSwitch } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlSwitch
     style={{
       '--width': '80px',
       '--height': '32px',
       '--thumb-size': '26px'
-    }} 
+    }}
   />
 );
 ```

docs/components/tab-group.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-tab-group]
 
-Tab groups organize content into a container that shows one section at a time.
-
 Tab groups make use of [tabs](/components/tab) and [tab panels](/components/tab-panel). Each tab must be slotted into the `nav` slot and its `panel` must refer to a tab panel of the same name.
 
 ```html preview
@@ -25,10 +23,18 @@ import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/rea
 
 const App = () => (
   <SlTabGroup>
-    <SlTab slot="nav" panel="general">General</SlTab>
-    <SlTab slot="nav" panel="custom">Custom</SlTab>
-    <SlTab slot="nav" panel="advanced">Advanced</SlTab>
-    <SlTab slot="nav" panel="disabled" disabled>Disabled</SlTab>
+    <SlTab slot="nav" panel="general">
+      General
+    </SlTab>
+    <SlTab slot="nav" panel="custom">
+      Custom
+    </SlTab>
+    <SlTab slot="nav" panel="advanced">
+      Advanced
+    </SlTab>
+    <SlTab slot="nav" panel="disabled" disabled>
+      Disabled
+    </SlTab>
 
     <SlTabPanel name="general">This is the general tab panel.</SlTabPanel>
     <SlTabPanel name="custom">This is the custom tab panel.</SlTabPanel>
@@ -63,10 +69,18 @@ import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/rea
 
 const App = () => (
   <SlTabGroup placement="bottom">
-    <SlTab slot="nav" panel="general">General</SlTab>
-    <SlTab slot="nav" panel="custom">Custom</SlTab>
-    <SlTab slot="nav" panel="advanced">Advanced</SlTab>
-    <SlTab slot="nav" panel="disabled" disabled>Disabled</SlTab>
+    <SlTab slot="nav" panel="general">
+      General
+    </SlTab>
+    <SlTab slot="nav" panel="custom">
+      Custom
+    </SlTab>
+    <SlTab slot="nav" panel="advanced">
+      Advanced
+    </SlTab>
+    <SlTab slot="nav" panel="disabled" disabled>
+      Disabled
+    </SlTab>
 
     <SlTabPanel name="general">This is the general tab panel.</SlTabPanel>
     <SlTabPanel name="custom">This is the custom tab panel.</SlTabPanel>
@@ -94,16 +108,23 @@ Tabs can be shown on the starting side by setting `placement` to `start`.
 </sl-tab-group>
 ```
 
-
 ```jsx react
 import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlTabGroup placement="start">
-    <SlTab slot="nav" panel="general">General</SlTab>
-    <SlTab slot="nav" panel="custom">Custom</SlTab>
-    <SlTab slot="nav" panel="advanced">Advanced</SlTab>
-    <SlTab slot="nav" panel="disabled" disabled>Disabled</SlTab>
+    <SlTab slot="nav" panel="general">
+      General
+    </SlTab>
+    <SlTab slot="nav" panel="custom">
+      Custom
+    </SlTab>
+    <SlTab slot="nav" panel="advanced">
+      Advanced
+    </SlTab>
+    <SlTab slot="nav" panel="disabled" disabled>
+      Disabled
+    </SlTab>
 
     <SlTabPanel name="general">This is the general tab panel.</SlTabPanel>
     <SlTabPanel name="custom">This is the custom tab panel.</SlTabPanel>
@@ -131,16 +152,23 @@ Tabs can be shown on the ending side by setting `placement` to `end`.
 </sl-tab-group>
 ```
 
-
 ```jsx react
 import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <SlTabGroup placement="end">
-    <SlTab slot="nav" panel="general">General</SlTab>
-    <SlTab slot="nav" panel="custom">Custom</SlTab>
-    <SlTab slot="nav" panel="advanced">Advanced</SlTab>
-    <SlTab slot="nav" panel="disabled" disabled>Disabled</SlTab>
+    <SlTab slot="nav" panel="general">
+      General
+    </SlTab>
+    <SlTab slot="nav" panel="custom">
+      Custom
+    </SlTab>
+    <SlTab slot="nav" panel="advanced">
+      Advanced
+    </SlTab>
+    <SlTab slot="nav" panel="disabled" disabled>
+      Disabled
+    </SlTab>
 
     <SlTabPanel name="general">This is the general tab panel.</SlTabPanel>
     <SlTabPanel name="custom">This is the custom tab panel.</SlTabPanel>
@@ -192,24 +220,32 @@ import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/rea
 const App = () => {
   function handleClose(event) {
     //
-    // This is a crude example that removes the tab and its panel from the DOM. 
+    // This is a crude example that removes the tab and its panel from the DOM.
     // There are better ways to manage tab creation/removal in React, but that
     // would significantly complicate the example.
     //
     const tab = event.target;
     const tabGroup = tab.closest('sl-tab-group');
     const tabPanel = tabGroup.querySelector(`[aria-labelledby="${tab.id}"]`);
-    
+
     tab.remove();
     tabPanel.remove();
   }
 
   return (
     <SlTabGroup className="tabs-closable" onSlClose={handleClose}>
-      <SlTab slot="nav" panel="general">General</SlTab>
-      <SlTab slot="nav" panel="closable-1" closable onSlClose={handleClose}>Closable 1</SlTab>
-      <SlTab slot="nav" panel="closable-2" closable onSlClose={handleClose}>Closable 2</SlTab>
-      <SlTab slot="nav" panel="closable-3" closable onSlClose={handleClose}>Closable 3</SlTab>
+      <SlTab slot="nav" panel="general">
+        General
+      </SlTab>
+      <SlTab slot="nav" panel="closable-1" closable onSlClose={handleClose}>
+        Closable 1
+      </SlTab>
+      <SlTab slot="nav" panel="closable-2" closable onSlClose={handleClose}>
+        Closable 2
+      </SlTab>
+      <SlTab slot="nav" panel="closable-3" closable onSlClose={handleClose}>
+        Closable 3
+      </SlTab>
 
       <SlTabPanel name="general">This is the general tab panel.</SlTabPanel>
       <SlTabPanel name="closable-1">This is the first closable tab panel.</SlTabPanel>
@@ -275,26 +311,66 @@ import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/rea
 
 const App = () => (
   <SlTabGroup>
-    <SlTab slot="nav" panel="tab-1">Tab 1</SlTab>
-    <SlTab slot="nav" panel="tab-2">Tab 2</SlTab>
-    <SlTab slot="nav" panel="tab-3">Tab 3</SlTab>
-    <SlTab slot="nav" panel="tab-4">Tab 4</SlTab>
-    <SlTab slot="nav" panel="tab-5">Tab 5</SlTab>
-    <SlTab slot="nav" panel="tab-6">Tab 6</SlTab>
-    <SlTab slot="nav" panel="tab-7">Tab 7</SlTab>
-    <SlTab slot="nav" panel="tab-8">Tab 8</SlTab>
-    <SlTab slot="nav" panel="tab-9">Tab 9</SlTab>
-    <SlTab slot="nav" panel="tab-10">Tab 10</SlTab>
-    <SlTab slot="nav" panel="tab-11">Tab 11</SlTab>
-    <SlTab slot="nav" panel="tab-12">Tab 12</SlTab>
-    <SlTab slot="nav" panel="tab-13">Tab 13</SlTab>
-    <SlTab slot="nav" panel="tab-14">Tab 14</SlTab>
-    <SlTab slot="nav" panel="tab-15">Tab 15</SlTab>
-    <SlTab slot="nav" panel="tab-16">Tab 16</SlTab>
-    <SlTab slot="nav" panel="tab-17">Tab 17</SlTab>
-    <SlTab slot="nav" panel="tab-18">Tab 18</SlTab>
-    <SlTab slot="nav" panel="tab-19">Tab 19</SlTab>
-    <SlTab slot="nav" panel="tab-20">Tab 20</SlTab>
+    <SlTab slot="nav" panel="tab-1">
+      Tab 1
+    </SlTab>
+    <SlTab slot="nav" panel="tab-2">
+      Tab 2
+    </SlTab>
+    <SlTab slot="nav" panel="tab-3">
+      Tab 3
+    </SlTab>
+    <SlTab slot="nav" panel="tab-4">
+      Tab 4
+    </SlTab>
+    <SlTab slot="nav" panel="tab-5">
+      Tab 5
+    </SlTab>
+    <SlTab slot="nav" panel="tab-6">
+      Tab 6
+    </SlTab>
+    <SlTab slot="nav" panel="tab-7">
+      Tab 7
+    </SlTab>
+    <SlTab slot="nav" panel="tab-8">
+      Tab 8
+    </SlTab>
+    <SlTab slot="nav" panel="tab-9">
+      Tab 9
+    </SlTab>
+    <SlTab slot="nav" panel="tab-10">
+      Tab 10
+    </SlTab>
+    <SlTab slot="nav" panel="tab-11">
+      Tab 11
+    </SlTab>
+    <SlTab slot="nav" panel="tab-12">
+      Tab 12
+    </SlTab>
+    <SlTab slot="nav" panel="tab-13">
+      Tab 13
+    </SlTab>
+    <SlTab slot="nav" panel="tab-14">
+      Tab 14
+    </SlTab>
+    <SlTab slot="nav" panel="tab-15">
+      Tab 15
+    </SlTab>
+    <SlTab slot="nav" panel="tab-16">
+      Tab 16
+    </SlTab>
+    <SlTab slot="nav" panel="tab-17">
+      Tab 17
+    </SlTab>
+    <SlTab slot="nav" panel="tab-18">
+      Tab 18
+    </SlTab>
+    <SlTab slot="nav" panel="tab-19">
+      Tab 19
+    </SlTab>
+    <SlTab slot="nav" panel="tab-20">
+      Tab 20
+    </SlTab>
 
     <SlTabPanel name="tab-1">Tab panel 1</SlTabPanel>
     <SlTabPanel name="tab-2">Tab panel 2</SlTabPanel>
@@ -343,10 +419,18 @@ import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/rea
 
 const App = () => (
   <SlTabGroup activation="manual">
-    <SlTab slot="nav" panel="general">General</SlTab>
-    <SlTab slot="nav" panel="custom">Custom</SlTab>
-    <SlTab slot="nav" panel="advanced">Advanced</SlTab>
-    <SlTab slot="nav" panel="disabled" disabled>Disabled</SlTab>
+    <SlTab slot="nav" panel="general">
+      General
+    </SlTab>
+    <SlTab slot="nav" panel="custom">
+      Custom
+    </SlTab>
+    <SlTab slot="nav" panel="advanced">
+      Advanced
+    </SlTab>
+    <SlTab slot="nav" panel="disabled" disabled>
+      Disabled
+    </SlTab>
 
     <SlTabPanel name="general">This is the general tab panel.</SlTabPanel>
     <SlTabPanel name="custom">This is the custom tab panel.</SlTabPanel>

docs/components/tab-panel.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-tab-panel]
 
-Tab panels are used inside [tab groups](/components/tab-group) to display tabbed content.
-
 ```html preview
 <sl-tab-group>
   <sl-tab slot="nav" panel="general">General</sl-tab>
@@ -23,10 +21,18 @@ import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/rea
 
 const App = () => (
   <SlTabGroup>
-    <SlTab slot="nav" panel="general">General</SlTab>
-    <SlTab slot="nav" panel="custom">Custom</SlTab>
-    <SlTab slot="nav" panel="advanced">Advanced</SlTab>
-    <SlTab slot="nav" panel="disabled" disabled>Disabled</SlTab>
+    <SlTab slot="nav" panel="general">
+      General
+    </SlTab>
+    <SlTab slot="nav" panel="custom">
+      Custom
+    </SlTab>
+    <SlTab slot="nav" panel="advanced">
+      Advanced
+    </SlTab>
+    <SlTab slot="nav" panel="disabled" disabled>
+      Disabled
+    </SlTab>
 
     <SlTabPanel name="general">This is the general tab panel.</SlTabPanel>
     <SlTabPanel name="custom">This is the custom tab panel.</SlTabPanel>

docs/components/tab.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-tab]
 
-Tabs are used inside [tab groups](/components/tab-group) to represent and activate [tab panels](/components/tab-panel).
-
 ```html preview
 <sl-tab>Tab</sl-tab>
 <sl-tab active>Active</sl-tab>

docs/components/tag.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-tag]
 
-Tags are used as labels to organize things or to indicate a selection.
-
 ```html preview
 <sl-tag variant="primary">Primary</sl-tag>
 <sl-tag variant="success">Success</sl-tag>
@@ -12,7 +10,6 @@ Tags are used as labels to organize things or to indicate a selection.
 <sl-tag variant="danger">Danger</sl-tag>
 ```
 
-
 ```jsx react
 import { SlTag } from '@shoelace-style/shoelace/dist/react';
 
@@ -22,7 +19,7 @@ const App = () => (
     <SlTag variant="success">Success</SlTag>
     <SlTag variant="neutral">Neutral</SlTag>
     <SlTag variant="warning">Warning</SlTag>
-    <SlTag variant="danger">Danger</SlTag> 
+    <SlTag variant="danger">Danger</SlTag>
   </>
 );
 ```
@@ -66,9 +63,15 @@ import { SlTag } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlTag size="small" pill>Small</SlTag>
-    <SlTag size="medium" pill>Medium</SlTag>
-    <SlTag size="large" pill>Large</SlTag>
+    <SlTag size="small" pill>
+      Small
+    </SlTag>
+    <SlTag size="medium" pill>
+      Medium
+    </SlTag>
+    <SlTag size="large" pill>
+      Large
+    </SlTag>
   </>
 );
 ```
@@ -90,7 +93,7 @@ Use the `removable` attribute to add a remove button to the tag.
   div.addEventListener('sl-remove', event => {
     const tag = event.target;
     tag.style.opacity = '0';
-    setTimeout(() => tag.style.opacity = '1', 2000);
+    setTimeout(() => (tag.style.opacity = '1'), 2000);
   });
 </script>
 
@@ -114,7 +117,7 @@ const App = () => {
   function handleRemove(event) {
     const tag = event.target;
     tag.style.opacity = '0';
-    setTimeout(() => tag.style.opacity = '1', 2000);
+    setTimeout(() => (tag.style.opacity = '1'), 2000);
   }
 
   return (
@@ -135,7 +138,7 @@ const App = () => {
 
       <style>{css}</style>
     </>
-  )
+  );
 };
 ```
 

docs/components/textarea.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-textarea]
 
-Textareas collect data from the user and allow multiple lines of text.
-
 ```html preview
 <sl-textarea></sl-textarea>
 ```
@@ -11,17 +9,41 @@ Textareas collect data from the user and allow multiple lines of text.
 ```jsx react
 import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlTextarea />
-);
+const App = () => <SlTextarea />;
 ```
 
-?> This component doesn't work with standard forms. Use [`<sl-form>`](/components/form) instead.
-
-?> Please refer to the section on [form control validation](/components/form?id=form-control-validation) to learn how to do client-side validation.
+?> This component works with standard `<form>` elements. Please refer to the section on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
 
 ## Examples
 
+### Labels
+
+Use the `label` attribute to give the textarea an accessible label. For labels that contain HTML, use the `label` slot instead.
+
+```html preview
+<sl-textarea label="Comments"></sl-textarea>
+```
+
+```jsx react
+import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => <SlTextarea label="Comments" />;
+```
+
+### Help Text
+
+Add descriptive help text to a textarea with the `help-text` attribute. For help texts that contain HTML, use the `help-text` slot instead.
+
+```html preview
+<sl-textarea label="Feedback" help-text="Please tell us what you think."> </sl-textarea>
+```
+
+```jsx react
+import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => <SlTextarea label="Feedback" help-text="Please tell us what you think." />;
+```
+
 ### Rows
 
 Use the `rows` attribute to change the number of text rows that get shown.
@@ -33,9 +55,7 @@ Use the `rows` attribute to change the number of text rows that get shown.
 ```jsx react
 import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlTextarea rows={2} />
-);
+const App = () => <SlTextarea rows={2} />;
 ```
 
 ### Placeholders
@@ -49,9 +69,7 @@ Use the `placeholder` attribute to add a placeholder.
 ```jsx react
 import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlTextarea placeholder="Type something" />
-);
+const App = () => <SlTextarea placeholder="Type something" />;
 ```
 
 ### Filled Textareas
@@ -65,9 +83,7 @@ Add the `filled` attribute to draw a filled textarea.
 ```jsx react
 import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlTextarea placeholder="Type something" filled />
-);
+const App = () => <SlTextarea placeholder="Type something" filled />;
 ```
 
 ### Disabled
@@ -81,9 +97,7 @@ Use the `disabled` attribute to disable a textarea.
 ```jsx react
 import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlTextarea placeholder="Textarea" disabled />
-);
+const App = () => <SlTextarea placeholder="Textarea" disabled />;
 ```
 
 ### Sizes
@@ -92,9 +106,9 @@ Use the `size` attribute to change a textarea's size.
 
 ```html preview
 <sl-textarea placeholder="Small" size="small"></sl-textarea>
-<br>
+<br />
 <sl-textarea placeholder="Medium" size="medium"></sl-textarea>
-<br>
+<br />
 <sl-textarea placeholder="Large" size="large"></sl-textarea>
 ```
 
@@ -112,45 +126,6 @@ const App = () => (
 );
 ```
 
-### Labels
-
-Use the `label` attribute to give the textarea an accessible label. For labels that contain HTML, use the `label` slot instead.
-
-```html preview
-<sl-textarea label="Comments"></sl-textarea>
-```
-
-```jsx react
-import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
-
-const App = () => (
-  <SlTextarea label="Comments" />
-);
-```
-
-### Help Text
-
-Add descriptive help text to a textarea with the `help-text` attribute. For help texts that contain HTML, use the `help-text` slot instead.
-
-```html preview
-<sl-textarea 
-  label="Feedback" 
-  help-text="Please tell us what you think."
->
-</sl-textarea>
-```
-
-```jsx react
-import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
-
-const App = () => (
-  <SlTextarea
-    label="Feedback"
-    help-text="Please tell us what you think."
-  />
-);
-```
-
 ### Prevent Resizing
 
 By default, textareas can be resized vertically by the user. To prevent resizing, set the `resize` attribute to `none`.
@@ -162,9 +137,7 @@ By default, textareas can be resized vertically by the user. To prevent resizing
 ```jsx react
 import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlTextarea resize="none" />
-);
+const App = () => <SlTextarea resize="none" />;
 ```
 
 ### Expand with Content
@@ -178,9 +151,7 @@ Textareas will automatically resize to expand to fit their content when `resize`
 ```jsx react
 import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
 
-const App = () => (
-  <SlTextarea resize="auto" />
-);
+const App = () => <SlTextarea resize="auto" />;
 ```
 
 [component-metadata:sl-textarea]

docs/components/tooltip.md

@@ -2,8 +2,6 @@
 
 [component-header:sl-tooltip]
 
-Tooltips display additional information based on a specific action.
-
 A tooltip's target is its _first child element_, so you should only wrap one element inside of the tooltip. If you need the tooltip to show up for multiple elements, nest them inside a container first.
 
 Tooltips use `display: contents` so they won't interfere with how elements are positioned in a flex or grid layout.
@@ -20,7 +18,7 @@ import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
 const App = () => (
   <SlTooltip content="This is a tooltip">
     <SlButton>Hover Me</SlButton>
-  </SlTooltip>  
+  </SlTooltip>
 );
 ```
 
@@ -94,6 +92,7 @@ Use the `placement` attribute to set the preferred placement of the tooltip.
 <style>
   .tooltip-placement-example {
     width: 250px;
+    margin: 1rem;
   }
 
   .tooltip-placement-example-row:after {
@@ -238,7 +237,7 @@ import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
 const App = () => (
   <SlTooltip content="Click again to dismiss" trigger="click">
     <SlButton>Click to Toggle</SlButton>
-  </SlTooltip>  
+  </SlTooltip>
 );
 ```
 
@@ -250,7 +249,7 @@ Tooltips can be controller programmatically by setting the `trigger` attribute t
 <sl-button style="margin-right: 4rem;">Toggle Manually</sl-button>
 
 <sl-tooltip content="This is an avatar" trigger="manual" class="manual-tooltip">
-  <sl-avatar></sl-avatar>
+  <sl-avatar label="User"></sl-avatar>
 </sl-tooltip>
 
 <script>
@@ -270,10 +269,7 @@ const App = () => {
 
   return (
     <>
-      <SlButton
-        style={{ marginRight: '4rem' }}
-        onClick={() => setOpen(!open)}
-      >
+      <SlButton style={{ marginRight: '4rem' }} onClick={() => setOpen(!open)}>
         Toggle Manually
       </SlButton>
 
@@ -285,20 +281,14 @@ const App = () => {
 };
 ```
 
-### Remove Arrows
+### Removing Arrows
 
-You can control the size of tooltip arrows by overriding the `--sl-tooltip-arrow-size` design token.
+You can control the size of tooltip arrows by overriding the `--sl-tooltip-arrow-size` design token. To remove them, set the value to `0` as shown below.
 
 ```html preview
-<div style="--sl-tooltip-arrow-size: 0;">
-  <sl-tooltip content="This is a tooltip">
-    <sl-button>Above</sl-button>
-  </sl-tooltip>
-
-  <sl-tooltip content="This is a tooltip" placement="bottom">
-    <sl-button>Below</sl-button>
-  </sl-tooltip>
-</div>
+<sl-tooltip content="This is a tooltip" style="--sl-tooltip-arrow-size: 0;">
+  <sl-button>No Arrow</sl-button>
+</sl-tooltip>
 ```
 
 ```jsx react
@@ -331,10 +321,8 @@ Use the `content` slot to create tooltips with HTML content. Tooltips are design
 
 ```html preview
 <sl-tooltip>
-  <div slot="content">
-    I'm not <strong>just</strong> a tooltip, I'm a <em>tooltip</em> with HTML!
-  </div>
-  
+  <div slot="content">I'm not <strong>just</strong> a tooltip, I'm a <em>tooltip</em> with HTML!</div>
+
   <sl-button>Hover me</sl-button>
 </sl-tooltip>
 ```
@@ -343,13 +331,33 @@ Use the `content` slot to create tooltips with HTML content. Tooltips are design
 import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlTooltip content="This is a tooltip">
+  <SlTooltip>
     <div slot="content">
       I'm not <strong>just</strong> a tooltip, I'm a <em>tooltip</em> with HTML!
     </div>
 
     <SlButton>Hover Me</SlButton>
-  </SlTooltip>  
+  </SlTooltip>
+);
+```
+
+### Setting a Maximum Width
+
+Use the `--max-width` custom property to change the width the tooltip can grow to before wrapping occurs.
+
+```html preview
+<sl-tooltip style="--max-width: 80px;" content="This tooltip will wrap after only 80 pixels.">
+  <sl-button>Hover me</sl-button>
+</sl-tooltip>
+```
+
+```jsx react
+import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTooltip style={{ '--max-width': '80px' }} content="This tooltip will wrap after only 80 pixels.">
+    <SlButton>Hover Me</SlButton>
+  </SlTooltip>
 );
 ```
 
@@ -370,10 +378,10 @@ Tooltips will be clipped if they're inside a container that has `overflow: auto|
 
 <style>
   .tooltip-hoist {
+    position: relative;
     border: solid 2px var(--sl-panel-border-color);
     overflow: hidden;
     padding: var(--sl-spacing-medium);
-    position: relative;
   }
 </style>
 ```

docs/components/tree-item.md

@@ -0,0 +1,163 @@
+# Tree Item
+
+[component-header:sl-tree-item]
+
+```html preview
+<sl-tree>
+  <sl-tree-item>
+    Item 1
+    <sl-tree-item>Item A</sl-tree-item>
+    <sl-tree-item>Item B</sl-tree-item>
+    <sl-tree-item>Item C</sl-tree-item>
+  </sl-tree-item>
+  <sl-tree-item>Item 2</sl-tree-item>
+  <sl-tree-item>Item 3</sl-tree-item>
+</sl-tree>
+```
+
+<!-- prettier-ignore -->
+```jsx react
+import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTree>
+    <SlTreeItem>
+      Item 1
+      <SlTreeItem>Item A</SlTreeItem>
+      <SlTreeItem>Item B</SlTreeItem>
+      <SlTreeItem>Item C</SlTreeItem>
+    </SlTreeItem>
+    <SlTreeItem>Item 2</SlTreeItem>
+    <SlTreeItem>Item 3</SlTreeItem>
+  </SlTree>
+);
+```
+
+## Examples
+
+### Nested tree items
+
+A tree item can contain other tree items. This allows the node to be expanded or collapsed by the user.
+
+```html preview
+<sl-tree>
+  <sl-tree-item>
+    Item 1
+    <sl-tree-item>
+      Item A
+      <sl-tree-item>Item Z</sl-tree-item>
+      <sl-tree-item>Item Y</sl-tree-item>
+      <sl-tree-item>Item X</sl-tree-item>
+    </sl-tree-item>
+    <sl-tree-item>Item B</sl-tree-item>
+    <sl-tree-item>Item C</sl-tree-item>
+  </sl-tree-item>
+  <sl-tree-item>Item 2</sl-tree-item>
+  <sl-tree-item>Item 3</sl-tree-item>
+</sl-tree>
+```
+
+<!-- prettier-ignore -->
+```jsx react
+import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTree>
+    <SlTreeItem>
+      Item 1
+      <SlTreeItem>
+        Item A
+        <SlTreeItem>Item Z</SlTreeItem>
+        <SlTreeItem>Item Y</SlTreeItem>
+        <SlTreeItem>Item X</SlTreeItem>
+      </SlTreeItem>
+      <SlTreeItem>Item B</SlTreeItem>
+      <SlTreeItem>Item C</SlTreeItem>
+    </SlTreeItem>
+    <SlTreeItem>Item 2</SlTreeItem>
+    <SlTreeItem>Item 3</SlTreeItem>
+  </SlTree>
+);
+```
+
+### Selected
+
+Use the `selected` attribute to select a tree item initially.
+
+```html preview
+<sl-tree>
+  <sl-tree-item selected>
+    Item 1
+    <sl-tree-item>Item A</sl-tree-item>
+    <sl-tree-item>Item B</sl-tree-item>
+    <sl-tree-item>Item C</sl-tree-item>
+  </sl-tree-item>
+  <sl-tree-item>Item 2</sl-tree-item>
+  <sl-tree-item>Item 3</sl-tree-item>
+</sl-tree>
+```
+
+<!-- prettier-ignore -->
+```jsx react
+import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTree>
+    <SlTreeItem selected>
+      Item 1
+      <SlTreeItem>Item A</SlTreeItem>
+      <SlTreeItem>Item B</SlTreeItem>
+      <SlTreeItem>Item C</SlTreeItem>
+    </SlTreeItem>
+    <SlTreeItem>Item 2</SlTreeItem>
+    <SlTreeItem>Item 3</SlTreeItem>
+  </SlTree>
+);
+```
+
+### Expanded
+
+Use the `expanded` attribute to expand a tree item initially.
+
+```html preview
+<sl-tree>
+  <sl-tree-item expanded>
+    Item 1
+    <sl-tree-item expanded>
+      Item A
+      <sl-tree-item>Item Z</sl-tree-item>
+      <sl-tree-item>Item Y</sl-tree-item>
+      <sl-tree-item>Item X</sl-tree-item>
+    </sl-tree-item>
+    <sl-tree-item>Item B</sl-tree-item>
+    <sl-tree-item>Item C</sl-tree-item>
+  </sl-tree-item>
+  <sl-tree-item>Item 2</sl-tree-item>
+  <sl-tree-item>Item 3</sl-tree-item>
+</sl-tree>
+```
+
+<!-- prettier-ignore -->
+```jsx react
+import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTree>
+    <SlTreeItem expanded>
+      Item 1
+      <SlTreeItem expanded>
+        Item A
+        <SlTreeItem>Item Z</SlTreeItem>
+        <SlTreeItem>Item Y</SlTreeItem>
+        <SlTreeItem>Item X</SlTreeItem>
+      </SlTreeItem>
+      <SlTreeItem>Item B</SlTreeItem>
+      <SlTreeItem>Item C</SlTreeItem>
+    </SlTreeItem>
+    <SlTreeItem>Item 2</SlTreeItem>
+    <SlTreeItem>Item 3</SlTreeItem>
+  </SlTree>
+);
+```
+
+[component-metadata:sl-tree-item]

docs/components/tree.md

@@ -0,0 +1,464 @@
+# Tree
+
+[component-header:sl-tree]
+
+```html preview
+<sl-tree>
+  <sl-tree-item>
+    Deciduous
+    <sl-tree-item>Birch</sl-tree-item>
+    <sl-tree-item>
+      Maple
+      <sl-tree-item>Field maple</sl-tree-item>
+      <sl-tree-item>Red maple</sl-tree-item>
+      <sl-tree-item>Sugar maple</sl-tree-item>
+    </sl-tree-item>
+    <sl-tree-item>Oak</sl-tree-item>
+  </sl-tree-item>
+
+  <sl-tree-item>
+    Coniferous
+    <sl-tree-item>Cedar</sl-tree-item>
+    <sl-tree-item>Pine</sl-tree-item>
+    <sl-tree-item>Spruce</sl-tree-item>
+  </sl-tree-item>
+
+  <sl-tree-item>
+    Non-trees
+    <sl-tree-item>Bamboo</sl-tree-item>
+    <sl-tree-item>Cactus</sl-tree-item>
+    <sl-tree-item>Fern</sl-tree-item>
+  </sl-tree-item>
+</sl-tree>
+```
+
+<!-- prettier-ignore -->
+```jsx react
+import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTree>
+    <SlTreeItem>
+      Deciduous
+      <SlTreeItem>Birch</SlTreeItem>
+      <SlTreeItem>
+        Maple
+        <SlTreeItem>Field maple</SlTreeItem>
+        <SlTreeItem>Red maple</SlTreeItem>
+        <SlTreeItem>Sugar maple</SlTreeItem>
+      </SlTreeItem>
+      <SlTreeItem>Oak</SlTreeItem>
+    </SlTreeItem>
+
+    <SlTreeItem>
+      Coniferous
+      <SlTreeItem>Cedar</SlTreeItem>
+      <SlTreeItem>Pine</SlTreeItem>
+      <SlTreeItem>Spruce</SlTreeItem>
+    </SlTreeItem>
+
+    <SlTreeItem>
+      Non-trees
+      <SlTreeItem>Bamboo</SlTreeItem>
+      <SlTreeItem>Cactus</SlTreeItem>
+      <SlTreeItem>Fern</SlTreeItem>
+    </SlTreeItem>
+  </SlTree>
+);
+```
+
+## Examples
+
+### Selection Modes
+
+The `selection` attribute lets you change the selection behavior of the tree.
+
+- Use `single` to allow the selection of a single item (default).
+- Use `multiple` to allow the selection of multiple items.
+- Use `leaf` to only allow leaf nodes to be selected.
+
+```html preview
+<sl-select id="selection-mode" value="single" label="Selection">
+  <sl-option value="single">Single</sl-option>
+  <sl-option value="multiple">Multiple</sl-option>
+  <sl-option value="leaf">Leaf</sl-option>
+</sl-select>
+
+<br />
+
+<sl-tree class="tree-selectable">
+  <sl-tree-item>
+    Item 1
+    <sl-tree-item>
+      Item A
+      <sl-tree-item>Item Z</sl-tree-item>
+      <sl-tree-item>Item Y</sl-tree-item>
+      <sl-tree-item>Item X</sl-tree-item>
+    </sl-tree-item>
+    <sl-tree-item>Item B</sl-tree-item>
+    <sl-tree-item>Item C</sl-tree-item>
+  </sl-tree-item>
+  <sl-tree-item>Item 2</sl-tree-item>
+  <sl-tree-item>Item 3</sl-tree-item>
+</sl-tree>
+
+<script>
+  const selectionMode = document.querySelector('#selection-mode');
+  const tree = document.querySelector('.tree-selectable');
+
+  selectionMode.addEventListener('sl-change', () => {
+    tree.querySelectorAll('sl-tree-item').forEach(item => (item.selected = false));
+    tree.selection = selectionMode.value;
+  });
+</script>
+```
+
+<!-- prettier-ignore -->
+```jsx react
+import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [selection, setSelection] = useState('single');
+
+  return (
+    <>
+      <SlSelect label="Selection" value={selection} onSlChange={event => setSelection(event.target.value)}>
+        <SlMenuItem value="single">single</SlMenuItem>
+        <SlMenuItem value="multiple">multiple</SlMenuItem>
+        <SlMenuItem value="leaf">leaf</SlMenuItem>
+      </SlSelect>
+
+      <br />
+
+      <SlTree selection={selection}>
+        <SlTreeItem>
+          Item 1
+          <SlTreeItem>
+            Item A
+            <SlTreeItem>Item Z</SlTreeItem>
+            <SlTreeItem>Item Y</SlTreeItem>
+            <SlTreeItem>Item X</SlTreeItem>
+          </SlTreeItem>
+          <SlTreeItem>Item B</SlTreeItem>
+          <SlTreeItem>Item C</SlTreeItem>
+        </SlTreeItem>
+        <SlTreeItem>Item 2</SlTreeItem>
+        <SlTreeItem>Item 3</SlTreeItem>
+      </SlTree>
+    </>
+  );
+};
+```
+
+### Showing Indent Guides
+
+Indent guides can be drawn by setting `--indent-guide-width`. You can also change the color, offset, and style, using `--indent-guide-color`, `--indent-guide-style`, and `--indent-guide-offset`, respectively.
+
+```html preview
+<sl-tree class="tree-with-lines">
+  <sl-tree-item expanded>
+    Deciduous
+    <sl-tree-item>Birch</sl-tree-item>
+    <sl-tree-item expanded>
+      Maple
+      <sl-tree-item>Field maple</sl-tree-item>
+      <sl-tree-item>Red maple</sl-tree-item>
+      <sl-tree-item>Sugar maple</sl-tree-item>
+    </sl-tree-item>
+    <sl-tree-item>Oak</sl-tree-item>
+  </sl-tree-item>
+
+  <sl-tree-item>
+    Coniferous
+    <sl-tree-item>Cedar</sl-tree-item>
+    <sl-tree-item>Pine</sl-tree-item>
+    <sl-tree-item>Spruce</sl-tree-item>
+  </sl-tree-item>
+
+  <sl-tree-item>
+    Non-trees
+    <sl-tree-item>Bamboo</sl-tree-item>
+    <sl-tree-item>Cactus</sl-tree-item>
+    <sl-tree-item>Fern</sl-tree-item>
+  </sl-tree-item>
+</sl-tree>
+
+<style>
+  .tree-with-lines {
+    --indent-guide-width: 1px;
+  }
+</style>
+```
+
+<!-- prettier-ignore -->
+```jsx react
+import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTree class="tree-with-lines" style={{ '--indent-guide-width': '1px' }}>
+    <SlTreeItem expanded>
+      Deciduous
+      <SlTreeItem>Birch</SlTreeItem>
+      <SlTreeItem expanded>
+        Maple
+        <SlTreeItem>Field maple</SlTreeItem>
+        <SlTreeItem>Red maple</SlTreeItem>
+        <SlTreeItem>Sugar maple</SlTreeItem>
+      </SlTreeItem>
+      <SlTreeItem>Oak</SlTreeItem>
+    </SlTreeItem>
+
+    <SlTreeItem>
+      Coniferous
+      <SlTreeItem>Cedar</SlTreeItem>
+      <SlTreeItem>Pine</SlTreeItem>
+      <SlTreeItem>Spruce</SlTreeItem>
+    </SlTreeItem>
+
+    <SlTreeItem>
+      Non-trees
+      <SlTreeItem>Bamboo</SlTreeItem>
+      <SlTreeItem>Cactus</SlTreeItem>
+      <SlTreeItem>Fern</SlTreeItem>
+    </SlTreeItem>
+  </SlTree>
+);
+```
+
+### Lazy Loading
+
+Use the `lazy` attribute on a tree item to indicate that the content is not yet present and will be loaded later. When the user tries to expand the node, the `loading` state is set to `true` and the `sl-lazy-load` event will be emitted to allow you to load data asynchronously. The item will remain in a loading state until its content is changed.
+
+If you want to disable this behavior after the first load, simply remove the `lazy` attribute and, on the next expand, the existing content will be shown instead.
+
+```html preview
+<sl-tree>
+  <sl-tree-item lazy>Available Trees</sl-tree-item>
+</sl-tree>
+
+<script type="module">
+  const lazyItem = document.querySelector('sl-tree-item[lazy]');
+
+  lazyItem.addEventListener('sl-lazy-load', () => {
+    // Simulate asynchronous loading
+    setTimeout(() => {
+      const subItems = ['Birch', 'Cedar', 'Maple', 'Pine'];
+
+      for (const item of subItems) {
+        const treeItem = document.createElement('sl-tree-item');
+        treeItem.innerText = item;
+        lazyItem.append(treeItem);
+      }
+
+      // Disable lazy mode once the content has been loaded
+      lazyItem.lazy = false;
+    }, 1000);
+  });
+</script>
+```
+
+```jsx react
+import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [childItems, setChildItems] = useState([]);
+  const [lazy, setLazy] = useState(true);
+
+  const handleLazyLoad = () => {
+    // Simulate asynchronous loading
+    setTimeout(() => {
+      setChildItems(['Birch', 'Cedar', 'Maple', 'Pine']);
+
+      // Disable lazy mode once the content has been loaded
+      setLazy(false);
+    }, 1000);
+  };
+
+  return (
+    <SlTree>
+      <SlTreeItem lazy={lazy} onSlLazyLoad={handleLazyLoad}>
+        Available Trees
+        {childItems.map(item => (
+          <SlTreeItem>{item}</SlTreeItem>
+        ))}
+      </SlTreeItem>
+    </SlTree>
+  );
+};
+```
+
+### Customizing the Expand and Collapse Icons
+
+Use the `expand-icon` and `collapse-icon` slots to change the expand and collapse icons, respectively. To disable the animation, override the `rotate` property on the `expand-button` part as shown below.
+
+```html preview
+<sl-tree class="custom-icons">
+  <sl-icon name="plus-square" slot="expand-icon"></sl-icon>
+  <sl-icon name="dash-square" slot="collapse-icon"></sl-icon>
+
+  <sl-tree-item>
+    Deciduous
+    <sl-tree-item>Birch</sl-tree-item>
+    <sl-tree-item>
+      Maple
+      <sl-tree-item>Field maple</sl-tree-item>
+      <sl-tree-item>Red maple</sl-tree-item>
+      <sl-tree-item>Sugar maple</sl-tree-item>
+    </sl-tree-item>
+    <sl-tree-item>Oak</sl-tree-item>
+  </sl-tree-item>
+
+  <sl-tree-item>
+    Coniferous
+    <sl-tree-item>Cedar</sl-tree-item>
+    <sl-tree-item>Pine</sl-tree-item>
+    <sl-tree-item>Spruce</sl-tree-item>
+  </sl-tree-item>
+
+  <sl-tree-item>
+    Non-trees
+    <sl-tree-item>Bamboo</sl-tree-item>
+    <sl-tree-item>Cactus</sl-tree-item>
+    <sl-tree-item>Fern</sl-tree-item>
+  </sl-tree-item>
+</sl-tree>
+
+<style>
+  .custom-icons sl-tree-item::part(expand-button) {
+    /* Disable the expand/collapse animation */
+    rotate: none;
+  }
+</style>
+```
+
+<!-- prettier-ignore -->
+```jsx react
+import { SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTree>
+    <SlIcon name="plus-square" slot="expand-icon"></SlIcon>
+    <SlIcon name="dash-square" slot="collapse-icon"></SlIcon>
+
+    <SlTreeItem>
+      Deciduous
+      <SlTreeItem>Birch</SlTreeItem>
+      <SlTreeItem>
+        Maple
+        <SlTreeItem>Field maple</SlTreeItem>
+        <SlTreeItem>Red maple</SlTreeItem>
+        <SlTreeItem>Sugar maple</SlTreeItem>
+      </SlTreeItem>
+      <SlTreeItem>Oak</SlTreeItem>
+    </SlTreeItem>
+
+    <SlTreeItem>
+      Coniferous
+      <SlTreeItem>Cedar</SlTreeItem>
+      <SlTreeItem>Pine</SlTreeItem>
+      <SlTreeItem>Spruce</SlTreeItem>
+    </SlTreeItem>
+
+    <SlTreeItem>
+      Non-trees
+      <SlTreeItem>Bamboo</SlTreeItem>
+      <SlTreeItem>Cactus</SlTreeItem>
+      <SlTreeItem>Fern</SlTreeItem>
+    </SlTreeItem>
+  </SlTree>
+);
+```
+
+### With Icons
+
+Decorative icons can be used before labels to provide hints for each node.
+
+```html preview
+<sl-tree class="tree-with-icons">
+  <sl-tree-item expanded>
+    <sl-icon name="folder"></sl-icon>
+    Documents
+
+    <sl-tree-item>
+      <sl-icon name="folder"> </sl-icon>
+      Photos
+      <sl-tree-item>
+        <sl-icon name="image"></sl-icon>
+        birds.jpg
+      </sl-tree-item>
+      <sl-tree-item>
+        <sl-icon name="image"></sl-icon>
+        kitten.jpg
+      </sl-tree-item>
+      <sl-tree-item>
+        <sl-icon name="image"></sl-icon>
+        puppy.jpg
+      </sl-tree-item>
+    </sl-tree-item>
+
+    <sl-tree-item>
+      <sl-icon name="folder"></sl-icon>
+      Writing
+      <sl-tree-item>
+        <sl-icon name="file"></sl-icon>
+        draft.txt
+      </sl-tree-item>
+      <sl-tree-item>
+        <sl-icon name="file-pdf"></sl-icon>
+        final.pdf
+      </sl-tree-item>
+      <sl-tree-item>
+        <sl-icon name="file-bar-graph"></sl-icon>
+        sales.xls
+      </sl-tree-item>
+    </sl-tree-item>
+  </sl-tree-item>
+</sl-tree>
+```
+
+```jsx react
+import { SlIcon, SlTree, SlTreeItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  return (
+    <SlTree class="tree-with-icons">
+      <SlTreeItem expanded>
+        <SlIcon name="folder" />
+        Root
+        <SlTreeItem>
+          <SlIcon name="folder" />
+          Folder 1<SlTreeItem>
+            <SlIcon name="files" />
+            File 1 - 1
+          </SlTreeItem>
+          <SlTreeItem disabled>
+            <SlIcon name="files" />
+            File 1 - 2
+          </SlTreeItem>
+          <SlTreeItem>
+            <SlIcon name="files" />
+            File 1 - 3
+          </SlTreeItem>
+        </SlTreeItem>
+        <SlTreeItem>
+          <SlIcon name="files" />
+          Folder 2<SlTreeItem>
+            <SlIcon name="files" />
+            File 2 - 1
+          </SlTreeItem>
+          <SlTreeItem>
+            <SlIcon name="files" />
+            File 2 - 2
+          </SlTreeItem>
+        </SlTreeItem>
+        <SlTreeItem>
+          <SlIcon name="files" />
+          File 1
+        </SlTreeItem>
+      </SlTreeItem>
+    </SlTree>
+  );
+};
+```
+
+[component-metadata:sl-tree]

docs/components/visually-hidden.md

@@ -2,14 +2,12 @@
 
 [component-header:sl-visually-hidden]
 
-The visually hidden utility makes content accessible to assistive devices without displaying it on the screen.
-
 According to [The A11Y Project](https://www.a11yproject.com/posts/2013-01-11-how-to-hide-content/), "there are real world situations where visually hiding content may be appropriate, while the content should remain available to assistive technologies, such as screen readers. For instance, hiding a search field's label as a common magnifying glass icon is used in its stead."
 
 Since visually hidden content can receive focus when tabbing, the element will become visible when something inside receives focus. This behavior is intentional, as sighted keyboards user won't be able to determine where the focus indicator is without it.
 
 ```html preview
-<div style="min-height: 100px;">
+<div style="min-height: 1.875rem;">
   <sl-visually-hidden>
     <a href="#">Skip to main content</a>
   </sl-visually-hidden>
@@ -32,7 +30,7 @@ In this example, the link will open a new window. Screen readers will announce "
 
 ### Content Conveyed By Context
 
-Adding a title or label may seem redundant at times, but they're very helpful for unsighted users. Rather than omit them, you can provide context to unsighted users with visually hidden content.
+Adding a label may seem redundant at times, but they're very helpful for unsighted users. Rather than omit them, you can provide context to unsighted users with visually hidden content that will be announced by assistive devices such as screen readers.
 
 ```html preview
 <sl-card style="width: 100%; max-width: 360px;">

docs/frameworks/react.md

@@ -33,11 +33,7 @@ Every Shoelace component is available to import as a React component. Note that
 ```jsx
 import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
-const MyComponent = () => (
-  <SlButton variant="primary">
-    Click me
-  </SlButton>
-);
+const MyComponent = () => <SlButton variant="primary">Click me</SlButton>;
 
 export default MyComponent;
 ```
@@ -57,13 +53,8 @@ import { SlInput } from '@shoelace-style/shoelace/dist/react';
 function MyComponent() {
   const [value, setValue] = useState('');
 
-  return (
-    <SlInput 
-      value={value} 
-      onSlInput={event => setValue(event.target.value)} 
-    />
-  )
-};
+  return <SlInput value={value} onSlInput={event => setValue(event.target.value)} />;
+}
 
 export default MyComponent;
 ```
@@ -78,13 +69,8 @@ import type SlInputElement from '@shoelace-style/shoelace/dist/components/input/
 function MyComponent() {
   const [value, setValue] = useState('');
 
-  return (
-    <SlInput 
-      value={value} 
-      onSlInput={event => setValue((event.target as SlInputElement).value)} 
-    />
-  )
-};
+  return <SlInput value={value} onSlInput={event => setValue((event.target as SlInputElement).value)} />;
+}
 
 export default MyComponent;
 ```
@@ -124,8 +110,8 @@ Object.defineProperty(window, 'matchMedia', {
     removeListener: jest.fn(), // deprecated
     addEventListener: jest.fn(),
     removeEventListener: jest.fn(),
-    dispatchEvent: jest.fn(),
-  })),
+    dispatchEvent: jest.fn()
+  }))
 });
 ```
 

docs/frameworks/vue-2.md

@@ -0,0 +1,95 @@
+# Vue (version 2)
+
+Vue [plays nice](https://custom-elements-everywhere.com/#vue) with custom elements, so you can use Shoelace in your Vue apps with ease.
+
+!> These instructions are for Vue 2. If you're using Vue 3 or above, please see the [Vue 3 instructions](/frameworks/vue).
+
+## Installation
+
+To add Shoelace to your Vue app, install the package from npm.
+
+```bash
+npm install @shoelace-style/shoelace
+```
+
+Next, [include a theme](/getting-started/themes) and set the [base path](/getting-started/installation#setting-the-base-path) for icons and other assets. In this example, we'll import the light theme and use the CDN as a base path.
+
+```jsx
+import '@shoelace-style/shoelace/dist/themes/light.css';
+import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path';
+
+setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/');
+```
+
+?> If you'd rather not use the CDN for assets, you can create a build task that copies `node_modules/@shoelace-style/shoelace/dist/assets` into a public folder in your app. Then you can point the base path to that folder instead.
+
+## Configuration
+
+You'll need to tell Vue to ignore Shoelace components. This is pretty easy because they all start with `sl-`.
+
+```js
+import Vue from 'vue';
+import App from './App.vue';
+
+Vue.config.ignoredElements = [/sl-/];
+
+const app = new Vue({
+  render: h => h(App)
+});
+
+app.$mount('#app');
+```
+
+Now you can start using Shoelace components in your app!
+
+## Usage
+
+### Binding Complex Data
+
+When binding complex data such as objects and arrays, use the `.prop` modifier to make Vue bind them as a property instead of an attribute.
+
+```html
+<sl-color-picker :swatches.prop="mySwatches" />
+```
+
+### Two-way Binding
+
+One caveat is there's currently [no support for v-model on custom elements](https://github.com/vuejs/vue/issues/7830), but you can still achieve two-way binding manually.
+
+```html
+<!-- This doesn't work -->
+<sl-input v-model="name"></sl-input>
+<!-- This works, but it's a bit longer -->
+<sl-input :value="name" @input="name = $event.target.value"></sl-input>
+```
+
+If that's too verbose for your liking, you can use a custom directive instead. [This utility](https://www.npmjs.com/package/@shoelace-style/vue-sl-model) adds a custom directive that will work just like `v-model` but for Shoelace components. To install it, use this command.
+
+```bash
+npm install @shoelace-style/vue-sl-model@1
+```
+
+Next, import the directive and enable it like this.
+
+```js
+import Vue from 'vue';
+import ShoelaceModelDirective from '@shoelace-style/vue-sl-model';
+import App from './App.vue';
+
+Vue.use(ShoelaceModelDirective);
+Vue.config.ignoredElements = [/sl-/];
+
+const app = new Vue({
+  render: h => h(App)
+});
+
+app.$mount('#app');
+```
+
+Now you can use the `v-sl-model` directive to keep your data in sync!
+
+```html
+<sl-input v-sl-model="name"></sl-input>
+```
+
+?> Are you using Shoelace with Vue? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/vue-2.md)

docs/frameworks/vue.md

@@ -2,7 +2,7 @@
 
 Vue [plays nice](https://custom-elements-everywhere.com/#vue) with custom elements, so you can use Shoelace in your Vue apps with ease.
 
-?> These instructions are for Vue 2. If you're using Vue 3, [please help us update this page](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/vue.md).
+?> These instructions are for Vue 3 and above. If you're using Vue 2, please see the [Vue 2 instructions](/frameworks/vue-2).
 
 ## Installation
 
@@ -28,20 +28,67 @@ setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dis
 You'll need to tell Vue to ignore Shoelace components. This is pretty easy because they all start with `sl-`.
 
 ```js
-import { createApp } from 'vue';
-import App from './App.vue';
+import { fileURLToPath, URL } from 'url';
 
-const app = createApp(App);
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
 
-app.config.compilerOptions.isCustomElement = tag => tag.startsWith('sl-');
-
-app.mount('#app');
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [
+    vue({
+      template: {
+        compilerOptions: {
+          isCustomElement: tag => tag.startsWith('sl-')
+        }
+      }
+    })
+  ],
+  resolve: {
+    alias: {
+      '@': fileURLToPath(new URL('./src', import.meta.url))
+    }
+  }
+});
 ```
 
 Now you can start using Shoelace components in your app!
 
 ## Usage
 
+### QR code generator example
+
+```vue
+<template>
+  <div class="container">
+    <h1>QR code generator</h1>
+
+    <sl-input maxlength="255" clearable label="Value" v-model="qrCode"></sl-input>
+
+    <sl-qr-code :value="qrCode"></sl-qr-code>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+import '@shoelace-style/shoelace/dist/components/qr-code/qr-code.js';
+import '@shoelace-style/shoelace/dist/components/input/input.js';
+
+const qrCode = ref();
+</script>
+
+<style>
+.container {
+  max-width: 400px;
+  margin: 0 auto;
+}
+
+sl-input {
+  margin: var(--sl-spacing-large) 0;
+}
+</style>
+```
+
 ### Binding Complex Data
 
 When binding complex data such as objects and arrays, use the `.prop` modifier to make Vue bind them as a property instead of an attribute.
@@ -50,43 +97,4 @@ When binding complex data such as objects and arrays, use the `.prop` modifier t
 <sl-color-picker :swatches.prop="mySwatches" />
 ```
 
-### Two-way Binding
-
-One caveat is there's currently [no support for v-model on custom elements](https://github.com/vuejs/vue/issues/7830), but you can still achieve two-way binding manually.
-
-```html
-<!-- This doesn't work -->
-<sl-input v-model="name">
-
-<!-- This works, but it's a bit longer -->
-<sl-input :value="name" @input="name = $event.target.value">
-```
-
-If that's too verbose for your liking, you can use a custom directive instead. [This utility](https://www.npmjs.com/package/@shoelace-style/vue-sl-model) adds a custom directive that will work just like `v-model` but for Shoelace components. To install it, use this command.
-
-```bash
-npm install @shoelace-style/vue-sl-model
-```
-
-Next, import the directive and enable it like this.
-
-```js
-import ShoelaceModelDirective from '@shoelace-style/vue-sl-model';
-import { createApp } from 'vue';
-import App from './App.vue';
-
-const app = createApp(App);
-app.use(ShoelaceModelDirective);
-
-app.config.compilerOptions.isCustomElement = tag => tag.startsWith('sl-');
-
-app.mount('#app');
-```
-
-Now you can use the `v-sl-model` directive to keep your data in sync!
-
-```html
-<sl-input v-sl-model="name">
-```
-
 ?> Are you using Shoelace with Vue? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/vue.md)

docs/getting-started/customizing.md

@@ -29,7 +29,7 @@ To customize a design token, simply override it in your stylesheet using a `:roo
 }
 ```
 
-Many design tokens are described further along in this documentation. For a complete list, refer to `src/themes/light.styles.ts` in the project's [source code](https://github.com/shoelace-style/shoelace/blob/current/src/themes/light.styles.ts).
+Many design tokens are described further along in this documentation. For a complete list, refer to `src/themes/light.css` in the project's [source code](https://github.com/shoelace-style/shoelace/blob/current/src/themes/light.css).
 
 ## Component Parts
 
@@ -40,9 +40,7 @@ Shoelace components use a [shadow DOM](https://developer.mozilla.org/en-US/docs/
 Here's an example that modifies buttons with the `tomato-button` class.
 
 ```html preview
-<sl-button class="tomato-button">
-  Tomato Button
-</sl-button>
+<sl-button class="tomato-button"> Tomato Button </sl-button>
 
 <style>
   .tomato-button::part(base) {
@@ -51,15 +49,15 @@ Here's an example that modifies buttons with the `tomato-button` class.
   }
 
   .tomato-button::part(base):hover {
-    background: rgba(255, 99, 71, .1);
-  }  
+    background: rgba(255, 99, 71, 0.1);
+  }
 
   .tomato-button::part(base):active {
-    background: rgba(255, 99, 71, .2);
-  }    
+    background: rgba(255, 99, 71, 0.2);
+  }
 
   .tomato-button::part(base):focus-visible {
-    box-shadow: 0 0 0 3px rgba(255, 99, 71, .33);
+    box-shadow: 0 0 0 3px rgba(255, 99, 71, 0.33);
   }
 
   .tomato-button::part(label) {
@@ -74,9 +72,9 @@ At first glance, this approach might seem a bit verbose or even limiting, but it
 
 - The internal structure of a component will likely change as it evolves. By exposing component parts through an API, the internals can be reworked without fear of breaking customizations as long as its parts remain intact.
 
-- It encourages us to think more about how components are designed and how customizations should be allowed before users can take advantage of them. Once we opt a part into the component's API, it's guaranteed to be supported and can't be removed until a major version of the library is released.
+- It encourages us to think more about how components are designed and how customizations should be allowed before users can take advantage of them. Once we opt a part into the component's API, it's guaranteed to be supported and can't be removed until a major version of the library is released.
 
-Most (but not all) components expose parts. You can find them in each component's API documention under the "CSS Parts" section.
+Most (but not all) components expose parts. You can find them in each component's API documentation under the "CSS Parts" section.
 
 ## Custom Properties
 
@@ -110,7 +108,7 @@ Not all components expose CSS custom properties. For those that do, they can be
 
 Some components use animation, such as when a dialog is shown or hidden. Animations are performed using the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) rather than CSS. However, you can still customize them through Shoelace's animation registry. If a component has customizable animations, they'll be listed in the "Animation" section of its documentation.
 
-To customize a default animation, use the `setDefaultAnimation()` method. The function accepts an animation name (found in the component's docs) and an object with `keyframes` and `options` or `null` to disable the animation.
+To customize a default animation, use the `setDefaultAnimation()` method. The function accepts an animation name (found in the component's docs) and an object with `keyframes`, and `options` or `null` to disable the animation.
 
 This example will make all dialogs use a custom show animation.
 
@@ -129,6 +127,8 @@ setDefaultAnimation('dialog.show', {
 });
 ```
 
+?> To support RTL languages in your animation, you can pass an additional property called `rtlKeyframes`. This property shares the same type as `keyframes` and will be automatically used when the component's directionality is RTL. If `rtlKeyframes` is not provided, `keyframes` will be used as a fallback.
+
 If you only want to target a single component, use the `setAnimation()` method instead. This function accepts an element, an animation name, and an object comprised of animation `keyframes` and `options`.
 
 In this example, only the target dialog will use a custom show animation.

docs/getting-started/form-controls.md

@@ -0,0 +1,500 @@
+# Form Controls
+
+Every Shoelace component makes use of a [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) to encapsulate markup, styles, and behavior. One caveat of this approach is that native `<form>` elements do not recognize form controls located inside a shadow root.
+
+Shoelace solves this problem by using the [`formdata`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/formdata_event) event, which is [available in all modern browsers](https://caniuse.com/mdn-api_htmlformelement_formdata_event). This means, when a form is submitted, Shoelace form controls will automatically append their values to the `FormData` object that's used to submit the form. In most cases, things will "just work." However, if you're using a form serialization library, it might need to be adapted to recognize Shoelace form controls.
+
+?> Shoelace uses event listeners to intercept the form's `formdata` and `submit` events. This allows it to inject data and trigger validation as necessary. If you're also attaching an event listener to the form, _you must attach it after Shoelace form controls are connected to the DOM_, otherwise your logic will run before Shoelace has a chance to inject form data and validate form controls.
+
+## Data Serialization
+
+Serialization is just a fancy word for collecting form data. If you're relying on standard form submissions, e.g. `<form action="...">`, you can probably skip this section. However, most modern apps use the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) or a library such as [axios](https://github.com/axios/axios) to submit forms using JavaScript.
+
+The [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) interface offers a standard way to serialize forms in the browser. You can create a `FormData` object from any `<form>` element like this.
+
+```js
+const form = document.querySelector('form');
+const data = new FormData(form);
+
+// All form control data is available in a FormData object
+```
+
+However, some folks find `FormData` tricky to work with or they need to pass a JSON payload to their server. To accommodate this, Shoelace offers a serialization utility that gathers form data and returns a simple JavaScript object instead.
+
+```js
+import { serialize } from '@shoelace-style/shoelace/dist/utilities/form.js';
+
+const form = document.querySelector('form');
+const data = serialize(form);
+
+// All form control data is available in a plain object
+```
+
+This results in an object with name/value pairs that map to each form control. If more than one form control shares the same name, the values will be passed as an array, e.g. `{ name: ['value1', 'value2'] }`.
+
+## Constraint Validation
+
+Client-side validation can be enabled through the browser's [Constraint Validation API](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation) for Shoelace form controls. You can activate it using attributes such as `required`, `pattern`, `minlength`, `maxlength`, etc. Shoelace implements many of the same attributes as native form controls, but check the documentation for a list of supported properties for each component.
+
+If you don't want to use client-side validation, you can suppress this behavior by adding `novalidate` to the surrounding `<form>` element.
+
+?> If this syntax looks unfamiliar, don't worry! Most of what you're learning on this page is platform knowledge that applies to regular form controls, too.
+
+!> Client-side validation can be used to improve the UX of forms, but it is not a replacement for server-side validation. **You should always validate and sanitize user input on the server!**
+
+### Required Fields
+
+To make a field required, use the `required` attribute. Required fields will automatically receive a `*` after their labels. This is configurable through the `--sl-input-required-content` custom property.
+
+The form will not be submitted if a required field is incomplete.
+
+```html preview
+<form class="input-validation-required">
+  <sl-input name="name" label="Name" required></sl-input>
+  <br />
+  <sl-select label="Favorite Animal" clearable required>
+    <sl-option value="birds">Birds</sl-option>
+    <sl-option value="cats">Cats</sl-option>
+    <sl-option value="dogs">Dogs</sl-option>
+    <sl-option value="other">Other</sl-option>
+  </sl-select>
+  <br />
+  <sl-textarea name="comment" label="Comment" required></sl-textarea>
+  <br />
+  <sl-checkbox required>Check me before submitting</sl-checkbox>
+  <br /><br />
+  <sl-button type="submit" variant="primary">Submit</sl-button>
+</form>
+
+<script type="module">
+  const form = document.querySelector('.input-validation-required');
+  form.addEventListener('submit', event => {
+    event.preventDefault();
+    alert('All fields are valid!');
+  });
+</script>
+```
+
+```jsx react
+import { SlButton, SlCheckbox, SlInput, SlMenuItem, SlSelect, SlTextarea } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  function handleSubmit(event) {
+    event.preventDefault();
+    alert('All fields are valid!');
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <SlInput name="name" label="Name" required />
+      <br />
+      <SlSelect label="Favorite Animal" clearable required>
+        <SlMenuItem value="birds">Birds</SlMenuItem>
+        <SlMenuItem value="cats">Cats</SlMenuItem>
+        <SlMenuItem value="dogs">Dogs</SlMenuItem>
+        <SlMenuItem value="other">Other</SlMenuItem>
+      </SlSelect>
+      <br />
+      <SlTextarea name="comment" label="Comment" required></SlTextarea>
+      <br />
+      <SlCheckbox required>Check me before submitting</SlCheckbox>
+      <br />
+      <br />
+      <SlButton type="submit" variant="primary">
+        Submit
+      </SlButton>
+    </form>
+  );
+};
+```
+
+### Input Patterns
+
+To restrict a value to a specific [pattern](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern), use the `pattern` attribute. This example only allows the letters A-Z, so the form will not submit if a number or symbol is entered. This only works with `<sl-input>` elements.
+
+```html preview
+<form class="input-validation-pattern">
+  <sl-input name="letters" required label="Letters" pattern="[A-Za-z]+"></sl-input>
+  <br />
+  <sl-button type="submit" variant="primary">Submit</sl-button>
+  <sl-button type="reset" variant="default">Reset</sl-button>
+</form>
+
+<script type="module">
+  const form = document.querySelector('.input-validation-pattern');
+  form.addEventListener('submit', event => {
+    event.preventDefault();
+    alert('All fields are valid!');
+  });
+</script>
+```
+
+```jsx react
+import { SlButton, SlInput } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  function handleSubmit(event) {
+    event.preventDefault();
+    alert('All fields are valid!');
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <SlInput name="letters" required label="Letters" pattern="[A-Za-z]+" />
+      <br />
+      <SlButton type="submit" variant="primary">
+        Submit
+      </SlButton>
+    </form>
+  );
+};
+```
+
+### Input Types
+
+Some input types will automatically trigger constraints, such as `email` and `url`.
+
+```html preview
+<form class="input-validation-type">
+  <sl-input type="email" label="Email" placeholder="you@example.com" required></sl-input>
+  <br />
+  <sl-input type="url" label="URL" placeholder="https://example.com/" required></sl-input>
+  <br />
+  <sl-button type="submit" variant="primary">Submit</sl-button>
+  <sl-button type="reset" variant="default">Reset</sl-button>
+</form>
+
+<script type="module">
+  const form = document.querySelector('.input-validation-type');
+  form.addEventListener('submit', event => {
+    event.preventDefault();
+    alert('All fields are valid!');
+  });
+</script>
+```
+
+```jsx react
+import { SlButton, SlInput } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  function handleSubmit(event) {
+    event.preventDefault();
+    alert('All fields are valid!');
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <SlInput type="email" label="Email" placeholder="you@example.com" required />
+      <br />
+      <SlInput type="url" label="URL" placeholder="https://example.com/" required />
+      <br />
+      <SlButton type="submit" variant="primary">
+        Submit
+      </SlButton>
+    </form>
+  );
+};
+```
+
+### Custom Error Messages
+
+To create a custom validation error, pass a non-empty string to the `setCustomValidity()` method. This will override any existing validation constraints. The form will not be submitted when a custom validity is set and the browser will show a validation error when the containing form is submitted. To make the input valid again, call `setCustomValidity()` again with an empty string.
+
+```html preview
+<form class="input-validation-custom">
+  <sl-input label="Type “shoelace”" required></sl-input>
+  <br />
+  <sl-button type="submit" variant="primary">Submit</sl-button>
+  <sl-button type="reset" variant="default">Reset</sl-button>
+</form>
+
+<script type="module">
+  const form = document.querySelector('.input-validation-custom');
+  const input = form.querySelector('sl-input');
+
+  form.addEventListener('submit', event => {
+    event.preventDefault();
+    alert('All fields are valid!');
+  });
+
+  input.addEventListener('sl-input', () => {
+    if (input.value === 'shoelace') {
+      input.setCustomValidity('');
+    } else {
+      input.setCustomValidity("Hey, you're supposed to type 'shoelace' before submitting this!");
+    }
+  });
+</script>
+```
+
+```jsx react
+import { useRef, useState } from 'react';
+import { SlButton, SlInput } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const input = useRef(null);
+  const [value, setValue] = useState('');
+
+  function handleInput(event) {
+    setValue(event.target.value);
+
+    if (event.target.value === 'shoelace') {
+      input.current.setCustomValidity('');
+    } else {
+      input.current.setCustomValidity("Hey, you're supposed to type 'shoelace' before submitting this!");
+    }
+  }
+
+  function handleSubmit(event) {
+    event.preventDefault();
+    alert('All fields are valid!');
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <SlInput ref={input} label="Type 'shoelace'" required value={value} onSlInput={handleInput} />
+      <br />
+      <SlButton type="submit" variant="primary">
+        Submit
+      </SlButton>
+    </form>
+  );
+};
+```
+
+?> Custom validation can be applied to any form control that supports the `setCustomValidity()` method. It is not limited to inputs and textareas.
+
+## Custom Validation Styles
+
+Due to the many ways form controls are used, Shoelace doesn't provide out of the box validation styles for form controls as part of its default theme. Instead, the following attributes will be applied to reflect a control's validity as users interact with it. You can use them to create custom styles for any of the validation states you're interested in.
+
+- `data-required` - the form control is required
+- `data-optional` - the form control is optional
+- `data-invalid` - the form control is currently invalid
+- `data-valid` - the form control is currently valid
+- `data-user-invalid` - the form control is currently invalid and the user has interacted with it
+- `data-user-valid` - the form control is currently valid and the user has interacted with it
+
+These attributes map to the browser's built-in pseudo classes for validation: [`:required`](https://developer.mozilla.org/en-US/docs/Web/CSS/:required), [`:optional`](https://developer.mozilla.org/en-US/docs/Web/CSS/:optional), [`:invalid`](https://developer.mozilla.org/en-US/docs/Web/CSS/:invalid), [`:valid`](https://developer.mozilla.org/en-US/docs/Web/CSS/:valid), and the proposed [`:user-invalid`](https://developer.mozilla.org/en-US/docs/Web/CSS/:user-invalid) and [`:user-valid`](https://developer.mozilla.org/en-US/docs/Web/CSS/:user-valid).
+
+?> In the future, data attributes will be replaced with custom pseudo classes such as `:--valid` and `:--invalid`. Shoelace is using data attributes as a workaround until browsers support custom states through [`ElementInternals.states`](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/states).
+
+### Styling Invalid Form Controls
+
+You can target validity using any of the aforementioned data attributes, but it's usually preferable to target `data-user-invalid` and `data-user-valid` since they get applied only after a user interaction such as typing or submitting. This prevents empty form controls from appearing invalid immediately, which often results in a poor user experience.
+
+This example demonstrates custom validation styles using `data-user-invalid` and `data-user-valid`. Try Typing in the fields to see how validity changes with user input.
+
+```html preview
+<form class="validity-styles">
+  <sl-input
+    name="name"
+    label="Name"
+    help-text="What would you like people to call you?"
+    autocomplete="off"
+    required
+  ></sl-input>
+
+  <sl-select name="animal" label="Favorite Animal" help-text="Select the best option." clearable required>
+    <sl-option value="birds">Birds</sl-option>
+    <sl-option value="cats">Cats</sl-option>
+    <sl-option value="dogs">Dogs</sl-option>
+    <sl-option value="other">Other</sl-option>
+  </sl-select>
+
+  <sl-checkbox value="accept" required>Accept terms and conditions</sl-checkbox>
+
+  <sl-button type="submit" variant="primary">Submit</sl-button>
+  <sl-button type="reset" variant="default">Reset</sl-button>
+</form>
+
+<script type="module">
+  const form = document.querySelector('.validity-styles');
+  form.addEventListener('submit', event => {
+    event.preventDefault();
+    alert('All fields are valid!');
+  });
+</script>
+
+<style>
+  .validity-styles sl-input,
+  .validity-styles sl-select,
+  .validity-styles sl-checkbox {
+    display: block;
+    margin-bottom: var(--sl-spacing-medium);
+  }
+
+  /* user invalid styles */
+  .validity-styles sl-input[data-user-invalid]::part(base),
+  .validity-styles sl-select[data-user-invalid]::part(combobox),
+  .validity-styles sl-checkbox[data-user-invalid]::part(control) {
+    border-color: var(--sl-color-danger-600);
+  }
+
+  .validity-styles [data-user-invalid]::part(form-control-label),
+  .validity-styles [data-user-invalid]::part(form-control-help-text),
+  .validity-styles sl-checkbox[data-user-invalid]::part(label) {
+    color: var(--sl-color-danger-700);
+  }
+
+  .validity-styles sl-checkbox[data-user-invalid]::part(control) {
+    outline: none;
+  }
+
+  .validity-styles sl-input:focus-within[data-user-invalid]::part(base),
+  .validity-styles sl-select:focus-within[data-user-invalid]::part(combobox),
+  .validity-styles sl-checkbox:focus-within[data-user-invalid]::part(control) {
+    border-color: var(--sl-color-danger-600);
+    box-shadow: 0 0 0 var(--sl-focus-ring-width) var(--sl-color-danger-300);
+  }
+
+  /* User valid styles */
+  .validity-styles sl-input[data-user-valid]::part(base),
+  .validity-styles sl-select[data-user-valid]::part(combobox),
+  .validity-styles sl-checkbox[data-user-valid]::part(control) {
+    border-color: var(--sl-color-success-600);
+  }
+
+  .validity-styles [data-user-valid]::part(form-control-label),
+  .validity-styles [data-user-valid]::part(form-control-help-text),
+  .validity-styles sl-checkbox[data-user-valid]::part(label) {
+    color: var(--sl-color-success-700);
+  }
+
+  .validity-styles sl-checkbox[data-user-valid]::part(control) {
+    background-color: var(--sl-color-success-600);
+    outline: none;
+  }
+
+  .validity-styles sl-input:focus-within[data-user-valid]::part(base),
+  .validity-styles sl-select:focus-within[data-user-valid]::part(combobox),
+  .validity-styles sl-checkbox:focus-within[data-user-valid]::part(control) {
+    border-color: var(--sl-color-success-600);
+    box-shadow: 0 0 0 var(--sl-focus-ring-width) var(--sl-color-success-300);
+  }
+</style>
+```
+
+## Inline Form Validation
+
+By default, Shoelace form controls use the browser's tooltip-style error messages. No mechanism is provided to show errors inline, as there are too many opinions on how that would work when combined with native form controls and other custom elements. You can, however, implement your own solution using the following technique.
+
+To disable the browser's error messages, you need to cancel the `sl-invalid` event. Then you can apply your own inline validation errors. This example demonstrates a primitive way to do this.
+
+```html preview
+<form class="inline-validation">
+  <sl-input
+    name="name"
+    label="Name"
+    help-text="What would you like people to call you?"
+    autocomplete="off"
+    required
+  ></sl-input>
+
+  <div id="name-error" aria-live="polite" hidden></div>
+
+  <sl-button type="submit" variant="primary">Submit</sl-button>
+  <sl-button type="reset" variant="default">Reset</sl-button>
+</form>
+
+<script>
+  const form = document.querySelector('.inline-validation');
+  const nameError = document.querySelector('#name-error');
+
+  // A form control is invalid
+  form.addEventListener(
+    'sl-invalid',
+    event => {
+      // Suppress the browser's constraint validation message
+      event.preventDefault();
+
+      nameError.textContent = `Error: ${event.target.validationMessage}`;
+      nameError.hidden = false;
+
+      event.target.focus();
+    },
+    { capture: true } // you must use capture since sl-invalid doesn't bubble!
+  );
+
+  // Handle form submit
+  form.addEventListener('submit', event => {
+    event.preventDefault();
+    nameError.hidden = true;
+    nameError.textContent = '';
+    setTimeout(() => alert('All fields are valid'), 50);
+  });
+
+  // Handle form reset
+  form.addEventListener('reset', event => {
+    nameError.hidden = true;
+    nameError.textContent = '';
+  });
+</script>
+
+<style>
+  #name-error {
+    font-size: var(--sl-input-help-text-font-size-medium);
+    color: var(--sl-color-danger-700);
+  }
+
+  #name-error ~ sl-button {
+    margin-top: var(--sl-spacing-medium);
+  }
+
+  .inline-validation sl-input {
+    display: block;
+  }
+
+  /* user invalid styles */
+  .inline-validation sl-input[data-user-invalid]::part(base) {
+    border-color: var(--sl-color-danger-600);
+  }
+
+  .inline-validation [data-user-invalid]::part(form-control-label),
+  .inline-validation [data-user-invalid]::part(form-control-help-text) {
+    color: var(--sl-color-danger-700);
+  }
+
+  .inline-validation sl-input:focus-within[data-user-invalid]::part(base) {
+    border-color: var(--sl-color-danger-600);
+    box-shadow: 0 0 0 var(--sl-focus-ring-width) var(--sl-color-danger-300);
+  }
+
+  /* User valid styles */
+  .inline-validation sl-input[data-user-valid]::part(base) {
+    border-color: var(--sl-color-success-600);
+  }
+
+  .inline-validation [data-user-valid]::part(form-control-label),
+  .inline-validation [data-user-valid]::part(form-control-help-text) {
+    color: var(--sl-color-success-700);
+  }
+
+  .inline-validation sl-checkbox[data-user-valid]::part(control) {
+    background-color: var(--sl-color-success-600);
+    outline: none;
+  }
+
+  .inline-validation sl-input:focus-within[data-user-valid]::part(base) {
+    border-color: var(--sl-color-success-600);
+    box-shadow: 0 0 0 var(--sl-focus-ring-width) var(--sl-color-success-300);
+  }
+</style>
+```
+
+!> This example is meant to demonstrate the concept of providing your own error messages inline. It is not intended to scale to more complex forms. Users who want this functionality are encouraged to build a more appropriate validation solution using the techniques shown below. Depending on how you implement this feature, custom error messages may affect the accessibility of your form controls.
+
+## Getting Associated Form Controls
+
+At this time, using [`HTMLFormElement.elements`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/elements) will not return Shoelace form controls because the browser is unaware of their status as custom element form controls. Fortunately, Shoelace provides an `elements()` function that does something very similar. However, instead of returning an [`HTMLFormControlsCollection`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormControlsCollection), it returns an array of HTML and Shoelace form controls in the order they appear in the DOM.
+
+```js
+import { getFormControls } from '@shoelace-style/shoelace/dist/utilities/form.js';
+
+const form = document.querySelector('#my-form');
+const formControls = getFormControls(form);
+
+console.log(formControls); // e.g. [input, sl-input, ...]
+```
+
+?> You probably don't need this function! If you're gathering form data for submission, you probably want to use [Data Serialization](#data-serializing) instead.

docs/getting-started/installation.md

@@ -4,23 +4,35 @@ You can use Shoelace via CDN or by installing it locally. You can also [cherry p
 
 If you're using a framework, make sure to check out the pages for [React](/frameworks/react), [Vue](/frameworks/vue), and [Angular](/frameworks/angular).
 
-## CDN Installation (Easiest)
+## Autoloading (Experimental)
+
+The autoloader is the simplest and most efficient way to use Shoelace. A lightweight script watches the DOM for unregistered Shoelace elements and lazy loads them for you. This works for elements already on the page and elements that get added later on.
+
+<!-- prettier-ignore -->
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/light.css" />
+<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/shoelace-autoloader.js"></script>
+```
+
+?> While convenient, one caveat of autoloading is you may see a [Flash of Undefined Custom Elements](https://www.abeautifulsite.net/posts/flash-of-undefined-custom-elements/).
+
+## CDN Installation
 
 The easiest way to install Shoelace is with the CDN. Just add the following tags to your page to get all components and the default light theme.
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/light.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/light.css" />
 <script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/shoelace.js"></script>
 ```
 
-?> If you're only using a handful of components, it will be more efficient to [cherry pick](#cherry-picking) the ones you need.
+?> If you're only using a handful of components, it will be more efficient to [autoload](#autoloading-experimental) or [cherry pick](#cherry-picking) the ones you need.
 
 ### Dark Theme
 
 If you prefer to use the [dark theme](/getting-started/themes#dark-theme) instead, use this code and add `<html class="sl-theme-dark">` to the page.
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/dark.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/dark.css" />
 <script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/shoelace.js"></script>
 ```
 
@@ -29,10 +41,17 @@ If you prefer to use the [dark theme](/getting-started/themes#dark-theme) instea
 If you want to load the light or dark theme based on the user's `prefers-color-scheme` setting, use this. The `media` attributes ensure that only the user's preferred theme stylesheet loads and the `onload` attribute sets the appropriate [theme class](/getting-started/themes) on the `<html>` element.
 
 ```html
-<link rel="stylesheet" media="(prefers-color-scheme:light)" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/light.css">
-<link rel="stylesheet" media="(prefers-color-scheme:dark)"
-      href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/dark.css"
-      onload="document.documentElement.classList.add('sl-theme-dark');">
+<link
+  rel="stylesheet"
+  media="(prefers-color-scheme:light)"
+  href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/light.css"
+/>
+<link
+  rel="stylesheet"
+  media="(prefers-color-scheme:dark)"
+  href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/dark.css"
+  onload="document.documentElement.classList.add('sl-theme-dark');"
+/>
 <script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/shoelace.js"></script>
 ```
 
@@ -51,7 +70,7 @@ It's up to you to make the source files available to your app. One way to do thi
 Once you've done that, add the following tags to your page. Make sure to update `href` and `src` so they point to the route you created.
 
 ```html
-<link rel="stylesheet" href="/shoelace/dist/themes/light.css">
+<link rel="stylesheet" href="/shoelace/dist/themes/light.css" />
 <script type="module" src="/shoelace/dist/shoelace.js"></script>
 ```
 
@@ -61,7 +80,7 @@ Alternatively, [you can use a bundler](#bundling).
 
 ## Setting the Base Path
 
-Some components rely on assets (icons, images, etc.) and Shoelace needs to know where they're located. For convenience, Shoelace will try to auto-detect the correct location based on the script you've loaded it from. This assumes assets are colocated with `shoelace.js` and will "just work" for most users.
+Some components rely on assets (icons, images, etc.) and Shoelace needs to know where they're located. For convenience, Shoelace will try to auto-detect the correct location based on the script you've loaded it from. This assumes assets are colocated with `shoelace.js` or `shoelace-autoloader.js` and will "just work" for most users.
 
 However, if you're [cherry picking](#cherry-picking) or [bundling](#bundling) Shoelace, you'll need to set the base path. You can do this one of two ways.
 
@@ -83,12 +102,12 @@ However, if you're [cherry picking](#cherry-picking) or [bundling](#bundling) Sh
 
 The previous approach is the _easiest_ way to load Shoelace, but easy isn't always efficient. You'll incur the full size of the library even if you only use a handful of components. This is convenient for prototyping or if you're using most of the components, but it may result in longer load times in production. To improve this, you can cherry pick the components you need.
 
-Cherry picking can be done from your local install or [directly from the CDN](https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/). This will limit the number of files the browser has to download and reduce the amount of bytes being transferred. The disadvantage is that you need to load component manually.
+Cherry picking can be done from your local install or [directly from the CDN](https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/). This will limit the number of files the browser has to download and reduce the amount of bytes being transferred. The disadvantage is that you need to load components manually.
 
 Here's an example that loads only the button component. Again, if you're not using a module resolver, you'll need to adjust the path to point to the folder Shoelace is in.
 
 ```html
-<link rel="stylesheet" href="/path/to/shoelace/dist/themes/light.css">
+<link rel="stylesheet" href="/path/to/shoelace/dist/themes/light.css" />
 
 <script type="module" data-shoelace="/path/to/shoelace/dist">
   import '@shoelace-style/shoelace/dist/components/button/button.js';