2.0.0

This reverts commit 4a3f2caf59.

.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: [16.x, 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

.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,154 @@
+{
+  "version": "0.2",
+  "words": [
+    "activedescendant",
+    "allowfullscreen",
+    "animationend",
+    "Animista",
+    "apos",
+    "atrule",
+    "autocorrect",
+    "autofix",
+    "autoplay",
+    "bezier",
+    "boxicons",
+    "callout",
+    "callouts",
+    "chatbubble",
+    "checkmark",
+    "claviska",
+    "Clippy",
+    "codebases",
+    "codepen",
+    "colocated",
+    "colour",
+    "combobox",
+    "Composability",
+    "Consolas",
+    "contenteditable",
+    "copydir",
+    "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",
+    "giga",
+    "globby",
+    "Grayscale",
+    "haspopup",
+    "heroicons",
+    "hexa",
+    "Iconoir",
+    "Iframes",
+    "iife",
+    "inputmode",
+    "ionicon",
+    "ionicons",
+    "jsDelivr",
+    "jsfiddle",
+    "jsonata",
+    "keydown",
+    "keyframes",
+    "labelledby",
+    "Laravel",
+    "LaViska",
+    "listbox",
+    "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",
+    "saturationl",
+    "Schilp",
+    "scrollbars",
+    "Segoe",
+    "semibold",
+    "slotchange",
+    "spacebar",
+    "stylesheet",
+    "Tabbable",
+    "tabindex",
+    "tabler",
+    "tablist",
+    "tabpanel",
+    "templating",
+    "tera",
+    "textareas",
+    "textfield",
+    "tinycolor",
+    "transitionend",
+    "treeitem",
+    "Triaging",
+    "turbolinks",
+    "typeof",
+    "unbundles",
+    "unbundling",
+    "unicons",
+    "unsupportive",
+    "valpha",
+    "valuenow",
+    "valuetext",
+    "WEBP",
+    "Webpacker",
+    "wordmark"
+  ],
+  "ignorePaths": [
+    "package.json",
+    "package-lock.json",
+    ".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 commandLineArgs from 'command-line-args';
 import { parse } from 'comment-parser';
-import pascalCase from 'pascal-case';
+import { pascalCase } from 'pascal-case';
 
 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)
@@ -33,7 +38,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,16 +45,19 @@
   - [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)
   - [Select](/components/select)
   - [Skeleton](/components/skeleton)
   - [Spinner](/components/spinner)
+  - [Split Panel](/components/split-panel)
   - [Switch](/components/switch)
   - [Tab Group](/components/tab-group)
   - [Tab](/components/tab)
@@ -58,9 +65,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)
@@ -68,12 +78,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)
@@ -81,8 +92,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,31 +365,43 @@
         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">
-              <sl-badge type="neutral" pill>
+              <sl-badge variant="neutral" pill>
                 Since ${component.since || '?'}
               </sl-badge>
 
-              <sl-badge type="${badgeType}" pill style="text-transform: capitalize;">
+              <sl-badge variant="${badgeType}" pill style="text-transform: capitalize;">
                 ${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

@@ -50,6 +50,8 @@ strong {
 }
 
 .sidebar-buttons {
+  display: flex;
+  justify-content: space-between;
   text-align: center;
   margin-top: 0;
 }
@@ -74,8 +76,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 +292,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 +314,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 +329,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 +344,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 +360,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 +373,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 +410,7 @@ kbd,
 }
 
 .markdown-section tr:nth-child(2n) {
-  background: var(--sl-color-neutral-50);
+  background: transparent;
 }
 
 .markdown-section th {
@@ -426,6 +424,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 +436,10 @@ kbd,
   cursor: help;
 }
 
+.markdown-section .metadata-table {
+  margin-bottom: 0rem;
+}
+
 /* Iframes */
 .markdown-section iframe {
   border: none;
@@ -487,14 +490,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 +518,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 +537,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 +599,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 either inline or as toast notifications.
-
 ```html preview
 <sl-alert open>
   <sl-icon slot="icon" name="info-circle"></sl-icon>
@@ -26,47 +24,47 @@ const App = () => (
 
 ## Examples
 
-### Types
+### Variants
 
-Set the `type` attribute to change the alert's type.
+Set the `variant` attribute to change the alert's variant.
 
 ```html preview
-<sl-alert type="primary" open>
+<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 type="success" open>
+<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 type="neutral" open>
+<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 type="warning" open>
+<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 type="danger" open>
+<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>
 ```
 
@@ -75,42 +73,47 @@ import { SlAlert, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlAlert type="primary" open>
+    <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>
 
     <br />
 
-    <SlAlert type="success" open>
+    <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>
 
     <br />
 
-    <SlAlert type="neutral" open>
+    <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>
 
     <br />
 
-    <SlAlert type="warning" open>
+    <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>
 
     <br />
 
-    <SlAlert type="danger" open>
+    <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>
   </>
 );
@@ -121,7 +124,7 @@ const App = () => (
 Add the `closable` attribute to show a close button that will hide the alert.
 
 ```html preview
-<sl-alert type="primary" open closable class="alert-closable">
+<sl-alert variant="primary" open closable class="alert-closable">
   <sl-icon slot="icon" name="info-circle"></sl-icon>
   You can close this alert any time!
 </sl-alert>
@@ -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,16 +163,14 @@ const App = () => {
 Icons are optional. Simply omit the `icon` slot if you don't want them.
 
 ```html preview
-<sl-alert type="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
 import { SlAlert } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlAlert type="primary" open>
+  <SlAlert variant="primary" open>
     Nothing fancy here, just a simple alert.
   </SlAlert>
 );
@@ -185,9 +182,9 @@ Set the `duration` attribute to automatically hide an alert after a period of ti
 
 ```html preview
 <div class="alert-duration">
-  <sl-button type="primary">Show Alert</sl-button>
+  <sl-button variant="primary">Show Alert</sl-button>
 
-  <sl-alert type="primary" duration="3000" closable>
+  <sl-alert variant="primary" duration="3000" closable>
     <sl-icon slot="icon" name="info-circle"></sl-icon>
     This alert will automatically hide itself after three seconds, unless you interact with it.
   </sl-alert>
@@ -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 type="primary" onClick={() => setOpen(true)}>Show Alert</SlButton>
+        <SlButton variant="primary" onClick={() => setOpen(true)}>
+          Show Alert
+        </SlButton>
 
-        <SlAlert 
-          type="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>
@@ -256,39 +245,39 @@ You should always use the `closable` attribute so users can dismiss the notifica
 
 ```html preview
 <div class="alert-toast">
-  <sl-button type="primary">Primary</sl-button>
-  <sl-button type="success">Success</sl-button>
-  <sl-button type="neutral">Neutral</sl-button>
-  <sl-button type="warning">Warning</sl-button>
-  <sl-button type="danger">Danger</sl-button>
-  
-  <sl-alert type="primary" duration="3000" closable>
+  <sl-button variant="primary">Primary</sl-button>
+  <sl-button variant="success">Success</sl-button>
+  <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 type="success" duration="3000" closable>
+  <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 type="neutral" duration="3000" closable>
+  <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 type="warning" duration="3000" closable>
+  <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 type="danger" duration="3000" closable>
+  <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>
@@ -296,9 +285,9 @@ You should always use the `closable` attribute so users can dismiss the notifica
 <script>
   const container = document.querySelector('.alert-toast');
 
-  ['primary', 'success', 'neutral', 'warning', 'danger'].map(type => {
-    const button = container.querySelector(`sl-button[type="${type}"]`);
-    const alert = container.querySelector(`sl-alert[type="${type}"]`);
+  ['primary', 'success', 'neutral', 'warning', 'danger'].map(variant => {
+    const button = container.querySelector(`sl-button[variant="${variant}"]`);
+    const alert = container.querySelector(`sl-alert[variant="${variant}"]`);
 
     button.addEventListener('click', () => alert.toast());
   });
@@ -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();
@@ -326,53 +311,58 @@ const App = () => {
 
   return (
     <>
-      <SlButton type="primary" onClick={() => primary.current.toast()}>
+      <SlButton variant="primary" onClick={() => primary.current.toast()}>
         Primary
       </SlButton>
 
-      <SlButton type="success" onClick={() => success.current.toast()}>
+      <SlButton variant="success" onClick={() => success.current.toast()}>
         Success
       </SlButton>
 
-      <SlButton type="neutral" onClick={() => neutral.current.toast()}>
+      <SlButton variant="neutral" onClick={() => neutral.current.toast()}>
         Neutral
       </SlButton>
 
-      <SlButton type="warning" onClick={() => warning.current.toast()}>
+      <SlButton variant="warning" onClick={() => warning.current.toast()}>
         Warning
       </SlButton>
 
-      <SlButton type="danger" onClick={() => danger.current.toast()}>
+      <SlButton variant="danger" onClick={() => danger.current.toast()}>
         Danger
       </SlButton>
 
-      <SlAlert ref={primary} type="primary" duration="3000" closable>
+      <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} type="success" duration="3000" closable>
+      <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} type="neutral" duration="3000" closable>
+      <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} type="warning" duration="3000" closable>
+      <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} type="danger" duration="3000" closable>
+      <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>
     </>
@@ -386,7 +376,7 @@ For convenience, you can create a utility that emits toast notifications with a
 
 ```html preview
 <div class="alert-toast-wrapper">
-  <sl-button type="primary">Create Toast</sl-button>
+  <sl-button variant="primary">Create Toast</sl-button>
 </div>
 
 <script>
@@ -399,12 +389,12 @@ 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, type = 'primary', icon = 'info-circle', duration = 3000) {
+  function notify(message, variant = 'primary', icon = 'info-circle', duration = 3000) {
     const alert = Object.assign(document.createElement('sl-alert'), {
-      type: type,
+      variant,
       closable: true,
       duration: duration,
       innerHTML: `

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>
   </>
 );
 ```
@@ -308,7 +307,7 @@ Animations won't play until you apply the `play` attribute. You can omit it init
 ```html preview
 <div class="animation-form">
   <sl-animation name="rubberBand" duration="1000" iterations="1">
-    <sl-button type="primary">Click me</sl-button>
+    <sl-button variant="primary">Click me</sl-button>
   </sl-animation>
 </div>
 
@@ -332,14 +331,8 @@ const App = () => {
 
   return (
     <div class="animation-form">
-      <SlAnimation 
-        name="rubberBand" 
-        duration={1000} 
-        iterations={1} 
-        play={play}
-        onSlFinish={() => setPlay(false)}
-      >
-        <SlButton type="primary" onClick={() => setPlay(true)}>
+      <SlAnimation name="rubberBand" duration={1000} iterations={1} play={play} onSlFinish={() => setPlay(false)}>
+        <SlButton variant="primary" onClick={() => setPlay(true)}>
           Click me
         </SlButton>
       </SlAnimation>

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,23 +9,21 @@ 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
 
-### Types
+### Variants
 
-Set the `type` attribute to change the badge's type.
+Set the `variant` attribute to change the badge's variant.
 
 ```html preview
-<sl-badge type="primary">Primary</sl-badge>
-<sl-badge type="success">Success</sl-badge>
-<sl-badge type="neutral">Neutral</sl-badge>
-<sl-badge type="warning">Warning</sl-badge>
-<sl-badge type="danger">Danger</sl-badge>
+<sl-badge variant="primary">Primary</sl-badge>
+<sl-badge variant="success">Success</sl-badge>
+<sl-badge variant="neutral">Neutral</sl-badge>
+<sl-badge variant="warning">Warning</sl-badge>
+<sl-badge variant="danger">Danger</sl-badge>
 ```
 
 ```jsx react
@@ -35,11 +31,11 @@ import { SlBadge } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlBadge type="primary">Primary</SlBadge>
-    <SlBadge type="success">Success</SlBadge>
-    <SlBadge type="neutral">Neutral</SlBadge>
-    <SlBadge type="warning">Warning</SlBadge>
-    <SlBadge type="danger">Danger</SlBadge>  
+    <SlBadge variant="primary">Primary</SlBadge>
+    <SlBadge variant="success">Success</SlBadge>
+    <SlBadge variant="neutral">Neutral</SlBadge>
+    <SlBadge variant="warning">Warning</SlBadge>
+    <SlBadge variant="danger">Danger</SlBadge>
   </>
 );
 ```
@@ -49,11 +45,11 @@ const App = () => (
 Use the `pill` attribute to give badges rounded edges.
 
 ```html preview
-<sl-badge type="primary" pill>Primary</sl-badge>
-<sl-badge type="success" pill>Success</sl-badge>
-<sl-badge type="neutral" pill>Neutral</sl-badge>
-<sl-badge type="warning" pill>Warning</sl-badge>
-<sl-badge type="danger" pill>Danger</sl-badge>
+<sl-badge variant="primary" pill>Primary</sl-badge>
+<sl-badge variant="success" pill>Success</sl-badge>
+<sl-badge variant="neutral" pill>Neutral</sl-badge>
+<sl-badge variant="warning" pill>Warning</sl-badge>
+<sl-badge variant="danger" pill>Danger</sl-badge>
 ```
 
 ```jsx react
@@ -61,11 +57,21 @@ import { SlBadge } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlBadge type="primary" pill>Primary</SlBadge>
-    <SlBadge type="success" pill>Success</SlBadge>
-    <SlBadge type="neutral" pill>Neutral</SlBadge>
-    <SlBadge type="warning" pill>Warning</SlBadge>
-    <SlBadge type="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>
   </>
 );
 ```
@@ -76,11 +82,11 @@ Use the `pulse` attribute to draw attention to the badge with a subtle animation
 
 ```html preview
 <div class="badge-pulse">
-  <sl-badge type="primary" pill pulse>1</sl-badge>
-  <sl-badge type="success" pill pulse>1</sl-badge>
-  <sl-badge type="neutral" pill pulse>1</sl-badge>
-  <sl-badge type="warning" pill pulse>1</sl-badge>
-  <sl-badge type="danger" pill pulse>1</sl-badge>
+  <sl-badge variant="primary" pill pulse>1</sl-badge>
+  <sl-badge variant="success" pill pulse>1</sl-badge>
+  <sl-badge variant="neutral" pill pulse>1</sl-badge>
+  <sl-badge variant="warning" pill pulse>1</sl-badge>
+  <sl-badge variant="danger" pill pulse>1</sl-badge>
 </div>
 
 <style>
@@ -102,11 +108,21 @@ const css = `
 const App = () => (
   <>
     <div className="badge-pulse">
-      <SlBadge type="primary" pill pulse>1</SlBadge>
-      <SlBadge type="success" pill pulse>1</SlBadge>
-      <SlBadge type="neutral" pill pulse>1</SlBadge>
-      <SlBadge type="warning" pill pulse>1</SlBadge>
-      <SlBadge type="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,14 +140,14 @@ 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 type="warning" pill>8</sl-badge>
+  <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 type="danger" pill>6</sl-badge>
+  <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 type="warning" pill>8</SlBadge>
+      <SlBadge variant="warning" pill>
+        8
+      </SlBadge>
     </SlButton>
 
-    <SlButton style={{ marginLeft: '1rem' }}>
+    <SlButton style={{ marginInlineStart: '1rem' }}>
       Errors
-      <SlBadge type="danger" pill>6</SlBadge>
+      <SlBadge variant="danger" pill>
+        6
+      </SlBadge>
     </SlButton>
   </>
 );
@@ -163,10 +183,10 @@ 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" type="neutral" pill>4</sl-badge></sl-menu-item>
-  <sl-menu-item>Replies <sl-badge slot="suffix" type="neutral" pill>12</sl-badge></sl-menu-item>
+  <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>
 </sl-menu>
 ```
 
@@ -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" type="neutral" pill>4</SlBadge></SlMenuItem>
-    <SlMenuItem>Replies <SlBadge slot="suffix" type="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,45 +86,45 @@ 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 type="primary">Left</sl-button>
-  <sl-button type="primary">Center</sl-button>
-  <sl-button type="primary">Right</sl-button>
+<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 type="success">Left</sl-button>
-  <sl-button type="success">Center</sl-button>
-  <sl-button type="success">Right</sl-button>
+<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 type="neutral">Left</sl-button>
-  <sl-button type="neutral">Center</sl-button>
-  <sl-button type="neutral">Right</sl-button>
+<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 type="warning">Left</sl-button>
-  <sl-button type="warning">Center</sl-button>
-  <sl-button type="warning">Right</sl-button>
+<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 type="danger">Left</sl-button>
-  <sl-button type="danger">Center</sl-button>
-  <sl-button type="danger">Right</sl-button>
+<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>
 </sl-button-group>
 ```
 
@@ -133,42 +133,46 @@ import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlButtonGroup>
-      <SlButton type="primary">Left</SlButton>
-      <SlButton type="primary">Center</SlButton>
-      <SlButton type="primary">Right</SlButton>
+    <SlButtonGroup label="Alignment">
+      <SlButton variant="primary">Left</SlButton>
+      <SlButton variant="primary">Center</SlButton>
+      <SlButton variant="primary">Right</SlButton>
     </SlButtonGroup>
 
-    <br /><br />
+    <br />
+    <br />
 
-    <SlButtonGroup>
-      <SlButton type="success">Left</SlButton>
-      <SlButton type="success">Center</SlButton>
-      <SlButton type="success">Right</SlButton>
+    <SlButtonGroup label="Alignment">
+      <SlButton variant="success">Left</SlButton>
+      <SlButton variant="success">Center</SlButton>
+      <SlButton variant="success">Right</SlButton>
     </SlButtonGroup>
 
-    <br /><br />
+    <br />
+    <br />
 
-    <SlButtonGroup>
-      <SlButton type="neutral">Left</SlButton>
-      <SlButton type="neutral">Center</SlButton>
-      <SlButton type="neutral">Right</SlButton>
+    <SlButtonGroup label="Alignment">
+      <SlButton variant="neutral">Left</SlButton>
+      <SlButton variant="neutral">Center</SlButton>
+      <SlButton variant="neutral">Right</SlButton>
     </SlButtonGroup>
 
-    <br /><br />
+    <br />
+    <br />
 
-    <SlButtonGroup>
-      <SlButton type="warning">Left</SlButton>
-      <SlButton type="warning">Center</SlButton>
-      <SlButton type="warning">Right</SlButton>
+    <SlButtonGroup label="Alignment">
+      <SlButton variant="warning">Left</SlButton>
+      <SlButton variant="warning">Center</SlButton>
+      <SlButton variant="warning">Right</SlButton>
     </SlButtonGroup>
 
-    <br /><br />
+    <br />
+    <br />
 
-    <SlButtonGroup>
-      <SlButton type="danger">Left</SlButton>
-      <SlButton type="danger">Center</SlButton>
-      <SlButton type="danger">Right</SlButton>
+    <SlButtonGroup label="Alignment">
+      <SlButton variant="danger">Left</SlButton>
+      <SlButton variant="danger">Center</SlButton>
+      <SlButton variant="danger">Right</SlButton>
     </SlButtonGroup>
   </>
 );
@@ -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 type="primary">Save</sl-button>
+<sl-button-group label="Example Button Group">
+  <sl-button variant="primary">Save</sl-button>
   <sl-dropdown placement="bottom-end">
-    <sl-button slot="trigger" type="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,19 +317,13 @@ 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> 
-    <SlButton type="primary">Save</SlButton>
+  <SlButtonGroup label="Example Button Group">
+    <SlButton variant="primary">Save</SlButton>
     <SlDropdown placement="bottom-end">
-      <SlButton slot="trigger" type="primary" caret></SlButton>
+      <SlButton slot="trigger" variant="primary" caret></SlButton>
       <SlMenu>
         <SlMenuItem>Save</SlMenuItem>
         <SlMenuItem>Save as&hellip;</SlMenuItem>
@@ -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,24 +9,22 @@ 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
 
-### Types
+### Variants
 
-Use the `type` attribute to set the button's type.
+Use the `variant` attribute to set the button's variant.
 
 ```html preview
-<sl-button type="default">Default</sl-button>
-<sl-button type="primary">Primary</sl-button>
-<sl-button type="success">Success</sl-button>
-<sl-button type="neutral">Neutral</sl-button>
-<sl-button type="warning">Warning</sl-button>
-<sl-button type="danger">Danger</sl-button>
+<sl-button variant="default">Default</sl-button>
+<sl-button variant="primary">Primary</sl-button>
+<sl-button variant="success">Success</sl-button>
+<sl-button variant="neutral">Neutral</sl-button>
+<sl-button variant="warning">Warning</sl-button>
+<sl-button variant="danger">Danger</sl-button>
 ```
 
 ```jsx react
@@ -36,12 +32,12 @@ import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlButton type="default">Default</SlButton>
-    <SlButton type="primary">Primary</SlButton>
-    <SlButton type="success">Success</SlButton>
-    <SlButton type="neutral">Neutral</SlButton>
-    <SlButton type="warning">Warning</SlButton>
-    <SlButton type="danger">Danger</SlButton>  
+    <SlButton variant="default">Default</SlButton>
+    <SlButton variant="primary">Primary</SlButton>
+    <SlButton variant="success">Success</SlButton>
+    <SlButton variant="neutral">Neutral</SlButton>
+    <SlButton variant="warning">Warning</SlButton>
+    <SlButton variant="danger">Danger</SlButton>
   </>
 );
 ```
@@ -73,12 +69,12 @@ const App = () => (
 Use the `outline` attribute to draw outlined buttons with transparent backgrounds.
 
 ```html preview
-<sl-button type="default" outline>Default</sl-button>
-<sl-button type="primary" outline>Primary</sl-button>
-<sl-button type="success" outline>Success</sl-button>
-<sl-button type="neutral" outline>Neutral</sl-button>
-<sl-button type="warning" outline>Warning</sl-button>
-<sl-button type="danger" outline>Danger</sl-button>
+<sl-button variant="default" outline>Default</sl-button>
+<sl-button variant="primary" outline>Primary</sl-button>
+<sl-button variant="success" outline>Success</sl-button>
+<sl-button variant="neutral" outline>Neutral</sl-button>
+<sl-button variant="warning" outline>Warning</sl-button>
+<sl-button variant="danger" outline>Danger</sl-button>
 ```
 
 ```jsx react
@@ -86,12 +82,24 @@ import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlButton type="default" outline>Default</SlButton>
-    <SlButton type="primary" outline>Primary</SlButton>
-    <SlButton type="success" outline>Success</SlButton>
-    <SlButton type="neutral" outline>Neutral</SlButton>
-    <SlButton type="warning" outline>Warning</SlButton>
-    <SlButton type="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 type="default" size="small" circle><sl-icon name="gear"></sl-icon></sl-button>
-<sl-button type="default" size="medium" circle><sl-icon name="gear"></sl-icon></sl-button>
-<sl-button type="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,21 +155,27 @@ import { SlButton, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlButton type="default" size="small" circle><SlIcon name="gear" /></SlButton>
-    <SlButton type="default" size="medium" circle><SlIcon name="gear" /></SlButton>
-    <SlButton type="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>
   </>
 );
 ```
 
 ### Text Buttons
 
-Use the `text` type to create text buttons that share the same size as regular buttons but don't have backgrounds or borders.
+Use the `text` variant to create text buttons that share the same size as regular buttons but don't have backgrounds or borders.
 
 ```html preview
-<sl-button type="text" size="small">Text</sl-button>
-<sl-button type="text" size="medium">Text</sl-button>
-<sl-button type="text" size="large">Text</sl-button>
+<sl-button variant="text" size="small">Text</sl-button>
+<sl-button variant="text" size="medium">Text</sl-button>
+<sl-button variant="text" size="large">Text</sl-button>
 ```
 
 ```jsx react
@@ -155,9 +183,15 @@ import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlButton type="text" size="small">Text</SlButton>
-    <SlButton type="text" size="medium">Text</SlButton>
-    <SlButton type="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>
   </>
 );
 ```
@@ -193,9 +233,9 @@ const App = () => (
 As expected, buttons can be given a custom width by setting the `width` attribute. This is useful for making buttons span the full width of their container on smaller screens.
 
 ```html preview
-<sl-button type="default" size="small" style="width: 100%; margin-bottom: 1rem;">Small</sl-button>
-<sl-button type="default" size="medium" style="width: 100%; margin-bottom: 1rem;">Medium</sl-button>
-<sl-button type="default" size="large" style="width: 100%;">Large</sl-button>
+<sl-button variant="default" size="small" style="width: 100%; margin-bottom: 1rem;">Small</sl-button>
+<sl-button variant="default" size="medium" style="width: 100%; margin-bottom: 1rem;">Medium</sl-button>
+<sl-button variant="default" size="large" style="width: 100%;">Large</sl-button>
 ```
 
 ```jsx react
@@ -203,9 +243,15 @@ import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlButton type="default" size="small" style={{ width: '100%', marginBottom: '1rem' }}>Small</SlButton>
-    <SlButton type="default" size="medium" style={{ width: '100%', marginBottom: '1rem' }}>Medium</SlButton>
-    <SlButton type="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>
   </>
 );
 ```
@@ -215,53 +261,53 @@ const App = () => (
 Use the `prefix` and `suffix` slots to add icons.
 
 ```html preview
-<sl-button type="default" size="small">
+<sl-button variant="default" size="small">
   <sl-icon slot="prefix" name="gear"></sl-icon>
   Settings
 </sl-button>
 
-<sl-button type="default" size="small">
+<sl-button variant="default" size="small">
   <sl-icon slot="suffix" name="arrow-counterclockwise"></sl-icon>
   Refresh
 </sl-button>
 
-<sl-button type="default" size="small">
+<sl-button variant="default" size="small">
   <sl-icon slot="prefix" name="link-45deg"></sl-icon>
   <sl-icon slot="suffix" name="box-arrow-up-right"></sl-icon>
   Open
 </sl-button>
 
-<br><br>
+<br /><br />
 
-<sl-button type="default">
+<sl-button variant="default">
   <sl-icon slot="prefix" name="gear"></sl-icon>
   Settings
 </sl-button>
 
-<sl-button type="default">
+<sl-button variant="default">
   <sl-icon slot="suffix" name="arrow-counterclockwise"></sl-icon>
   Refresh
 </sl-button>
 
-<sl-button type="default">
+<sl-button variant="default">
   <sl-icon slot="prefix" name="link-45deg"></sl-icon>
   <sl-icon slot="suffix" name="box-arrow-up-right"></sl-icon>
   Open
 </sl-button>
 
-<br><br>
+<br /><br />
 
-<sl-button type="default" size="large">
+<sl-button variant="default" size="large">
   <sl-icon slot="prefix" name="gear"></sl-icon>
   Settings
 </sl-button>
 
-<sl-button type="default" size="large">
+<sl-button variant="default" size="large">
   <sl-icon slot="suffix" name="arrow-counterclockwise"></sl-icon>
   Refresh
 </sl-button>
 
-<sl-button type="default" size="large">
+<sl-button variant="default" size="large">
   <sl-icon slot="prefix" name="link-45deg"></sl-icon>
   <sl-icon slot="suffix" name="box-arrow-up-right"></sl-icon>
   Open
@@ -273,53 +319,55 @@ import { SlButton, SlIcon } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlButton type="default" size="small">
+    <SlButton variant="default" size="small">
       <SlIcon slot="prefix" name="gear"></SlIcon>
       Settings
     </SlButton>
 
-    <SlButton type="default" size="small">
+    <SlButton variant="default" size="small">
       <SlIcon slot="suffix" name="arrow-counterclockwise"></SlIcon>
       Refresh
     </SlButton>
 
-    <SlButton type="default" size="small">
+    <SlButton variant="default" size="small">
       <SlIcon slot="prefix" name="link-45deg"></SlIcon>
       <SlIcon slot="suffix" name="box-arrow-up-right"></SlIcon>
       Open
     </SlButton>
 
-    <br /><br/ >
+    <br />
+    <br />
 
-    <SlButton type="default">
+    <SlButton variant="default">
       <SlIcon slot="prefix" name="gear"></SlIcon>
       Settings
     </SlButton>
 
-    <SlButton type="default">
+    <SlButton variant="default">
       <SlIcon slot="suffix" name="arrow-counterclockwise"></SlIcon>
       Refresh
     </SlButton>
 
-    <SlButton type="default">
+    <SlButton variant="default">
       <SlIcon slot="prefix" name="link-45deg"></SlIcon>
       <SlIcon slot="suffix" name="box-arrow-up-right"></SlIcon>
       Open
     </SlButton>
 
-    <br /><br />
+    <br />
+    <br />
 
-    <SlButton type="default" size="large">
+    <SlButton variant="default" size="large">
       <SlIcon slot="prefix" name="gear"></SlIcon>
       Settings
     </SlButton>
 
-    <SlButton type="default" size="large">
+    <SlButton variant="default" size="large">
       <SlIcon slot="suffix" name="arrow-counterclockwise"></SlIcon>
       Refresh
     </SlButton>
 
-    <SlButton type="default" size="large">
+    <SlButton variant="default" size="large">
       <SlIcon slot="prefix" name="link-45deg"></SlIcon>
       <SlIcon slot="suffix" name="box-arrow-up-right"></SlIcon>
       Open
@@ -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>
   </>
 );
 ```
@@ -355,12 +409,12 @@ const App = () => (
 Use the `loading` attribute to make a button busy. The width will remain the same as before, preventing adjacent elements from moving around. Clicks will be suppressed until the loading state is removed.
 
 ```html preview
-<sl-button type="default" loading>Default</sl-button>
-<sl-button type="primary" loading>Primary</sl-button>
-<sl-button type="success" loading>Success</sl-button>
-<sl-button type="neutral" loading>Neutral</sl-button>
-<sl-button type="warning" loading>Warning</sl-button>
-<sl-button type="danger" loading>Danger</sl-button>
+<sl-button variant="default" loading>Default</sl-button>
+<sl-button variant="primary" loading>Primary</sl-button>
+<sl-button variant="success" loading>Success</sl-button>
+<sl-button variant="neutral" loading>Neutral</sl-button>
+<sl-button variant="warning" loading>Warning</sl-button>
+<sl-button variant="danger" loading>Danger</sl-button>
 ```
 
 ```jsx react
@@ -368,12 +422,24 @@ import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlButton type="default" loading>Default</SlButton>
-    <SlButton type="primary" loading>Primary</SlButton>
-    <SlButton type="success" loading>Success</SlButton>
-    <SlButton type="neutral" loading>Neutral</SlButton>
-    <SlButton type="warning" loading>Warning</SlButton>
-    <SlButton type="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>
   </>
 );
 ```
@@ -383,12 +449,12 @@ const App = () => (
 Use the `disabled` attribute to disable a button. Clicks will be suppressed until the disabled state is removed.
 
 ```html preview
-<sl-button type="default" disabled>Default</sl-button>
-<sl-button type="primary" disabled>Primary</sl-button>
-<sl-button type="success" disabled>Success</sl-button>
-<sl-button type="neutral" disabled>Neutral</sl-button>
-<sl-button type="warning" disabled>Warning</sl-button>
-<sl-button type="danger" disabled>Danger</sl-button>
+<sl-button variant="default" disabled>Default</sl-button>
+<sl-button variant="primary" disabled>Primary</sl-button>
+<sl-button variant="success" disabled>Success</sl-button>
+<sl-button variant="neutral" disabled>Neutral</sl-button>
+<sl-button variant="warning" disabled>Warning</sl-button>
+<sl-button variant="danger" disabled>Danger</sl-button>
 ```
 
 ```jsx react
@@ -396,19 +462,36 @@ import { SlButton } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlButton type="default" disabled>Default</SlButton>
-    <SlButton type="primary" disabled>Primary</SlButton>
-    <SlButton type="success" disabled>Success</SlButton>
-    <SlButton type="neutral" disabled>Neutral</SlButton>
-    <SlButton type="warning" disabled>Warning</SlButton>
-    <SlButton type="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>
   </>
 );
 ```
 
 ### Styling Buttons
 
-This example demonstrates how to style buttons using a custom class. This is the recommended approach if you need to add additional variations. To customize an existing variation, modify the selector to target the button's type attribute instead of a class (e.g. `sl-button[type="primary"]`).
+This example demonstrates how to style buttons using a custom class. This is the recommended approach if you need to add additional variations. To customize an existing variation, modify the selector to target the button's `variant` attribute instead of a class (e.g. `sl-button[variant="primary"]`).
 
 ```html preview
 <sl-button class="pink">Pink Button</sl-button>
@@ -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,22 +2,20 @@
 
 [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">
-    <sl-button type="primary" pill>More Info</sl-button>
+    <sl-button variant="primary" pill>More Info</sl-button>
     <sl-rating></sl-rating>
   </div>
 </sl-card>
@@ -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 type="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" type="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" type="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/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,101 @@ 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(() => {
+    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,13 +1,13 @@
+<!-- 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.
-  <sl-button slot="footer" type="primary">Close</sl-button>
+  <sl-button slot="footer" variant="primary">Close</sl-button>
 </sl-dialog>
 
 <sl-button>Open Dialog</sl-button>
@@ -33,7 +33,7 @@ const App = () => {
     <>
       <SlDialog label="Dialog" open={open} onSlAfterHide={() => setOpen(false)}>
         Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-        <SlButton slot="footer" type="primary" onClick={() => setOpen(false)}>
+        <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
           Close
         </SlButton>
       </SlDialog>
@@ -59,7 +59,7 @@ Use the `--width` custom property to set the dialog's width.
 ```html preview
 <sl-dialog label="Dialog" class="dialog-width" style="--width: 50vw;">
   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-  <sl-button slot="footer" type="primary">Close</sl-button>
+  <sl-button slot="footer" variant="primary">Close</sl-button>
 </sl-dialog>
 
 <sl-button>Open Dialog</sl-button>
@@ -83,14 +83,9 @@ 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" type="primary" onClick={() => setOpen(false)}>
+        <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
           Close
         </SlButton>
       </SlDialog>
@@ -110,7 +105,7 @@ By design, a dialog's height will never exceed that of the viewport. As such, di
   <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>
-  <sl-button slot="footer" type="primary">Close</sl-button>
+  <sl-button slot="footer" variant="primary">Close</sl-button>
 </sl-dialog>
 
 <sl-button>Open Dialog</sl-button>
@@ -135,15 +130,70 @@ 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>
 
-        <SlButton slot="footer" type="primary" onClick={() => setOpen(false)}>
+        <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
+          Close
+        </SlButton>
+      </SlDialog>
+
+      <SlButton onClick={() => setOpen(true)}>Open Dialog</SlButton>
+    </>
+  );
+};
+```
+
+### 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>
@@ -160,10 +210,12 @@ By default, dialogs will close when the user clicks the close button, clicks the
 
 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" type="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.
-        <SlButton slot="footer" type="primary" onClick={() => setOpen(false)}>
-          Save &amp; Close
+      <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)}>
+          Close
         </SlButton>
       </SlDialog>
 
@@ -209,12 +268,12 @@ 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-button slot="footer" type="primary">Close</sl-button>
+  <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>
 
 <sl-button>Open Dialog</sl-button>
@@ -227,41 +286,21 @@ 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" />
-        <SlButton slot="footer" type="primary" onClick={() => setOpen(false)}>
+      <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>
       </SlDialog>
@@ -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,13 +1,13 @@
+<!-- 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.
-  <sl-button slot="footer" type="primary">Close</sl-button>
+  <sl-button slot="footer" variant="primary">Close</sl-button>
 </sl-drawer>
 
 <sl-button>Open Drawer</sl-button>
@@ -15,7 +15,7 @@ Drawers slide in from a container to expose additional options and information.
 <script>
   const drawer = document.querySelector('.drawer-overview');
   const openButton = drawer.nextElementSibling;
-  const closeButton = drawer.querySelector('sl-button[type="primary"]');
+  const closeButton = drawer.querySelector('sl-button[variant="primary"]');
 
   openButton.addEventListener('click', () => drawer.show());
   closeButton.addEventListener('click', () => drawer.hide());
@@ -33,7 +33,7 @@ const App = () => {
     <>
       <SlDrawer label="Drawer" open={open} onSlAfterHide={() => setOpen(false)}>
         Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-        <SlButton slot="footer" type="primary" onClick={() => setOpen(false)}>
+        <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
           Close
         </SlButton>
       </SlDrawer>
@@ -53,7 +53,7 @@ By default, drawers slide in from the end. To make the drawer slide in from the
 ```html preview
 <sl-drawer label="Drawer" placement="start" class="drawer-placement-start">
   This drawer slides in from the start.
-  <sl-button slot="footer" type="primary">Close</sl-button>
+  <sl-button slot="footer" variant="primary">Close</sl-button>
 </sl-drawer>
 
 <sl-button>Open Drawer</sl-button>
@@ -61,7 +61,7 @@ By default, drawers slide in from the end. To make the drawer slide in from the
 <script>
   const drawer = document.querySelector('.drawer-placement-start');
   const openButton = drawer.nextElementSibling;
-  const closeButton = drawer.querySelector('sl-button[type="primary"]');
+  const closeButton = drawer.querySelector('sl-button[variant="primary"]');
 
   openButton.addEventListener('click', () => drawer.show());
   closeButton.addEventListener('click', () => drawer.hide());
@@ -77,14 +77,9 @@ 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" type="primary" onClick={() => setOpen(false)}>
+        <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
           Close
         </SlButton>
       </SlDrawer>
@@ -102,7 +97,7 @@ To make the drawer slide in from the top, set the `placement` attribute to `top`
 ```html preview
 <sl-drawer label="Drawer" placement="top" class="drawer-placement-top">
   This drawer slides in from the top.
-  <sl-button slot="footer" type="primary">Close</sl-button>
+  <sl-button slot="footer" variant="primary">Close</sl-button>
 </sl-drawer>
 
 <sl-button>Open Drawer</sl-button>
@@ -110,7 +105,7 @@ To make the drawer slide in from the top, set the `placement` attribute to `top`
 <script>
   const drawer = document.querySelector('.drawer-placement-top');
   const openButton = drawer.nextElementSibling;
-  const closeButton = drawer.querySelector('sl-button[type="primary"]');
+  const closeButton = drawer.querySelector('sl-button[variant="primary"]');
 
   openButton.addEventListener('click', () => drawer.show());
   closeButton.addEventListener('click', () => drawer.hide());
@@ -126,14 +121,9 @@ 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" type="primary" onClick={() => setOpen(false)}>
+        <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
           Close
         </SlButton>
       </SlDrawer>
@@ -151,7 +141,7 @@ To make the drawer slide in from the bottom, set the `placement` attribute to `b
 ```html preview
 <sl-drawer label="Drawer" placement="bottom" class="drawer-placement-bottom">
   This drawer slides in from the bottom.
-  <sl-button slot="footer" type="primary">Close</sl-button>
+  <sl-button slot="footer" variant="primary">Close</sl-button>
 </sl-drawer>
 
 <sl-button>Open Drawer</sl-button>
@@ -159,7 +149,7 @@ To make the drawer slide in from the bottom, set the `placement` attribute to `b
 <script>
   const drawer = document.querySelector('.drawer-placement-bottom');
   const openButton = drawer.nextElementSibling;
-  const closeButton = drawer.querySelector('sl-button[type="primary"]');
+  const closeButton = drawer.querySelector('sl-button[variant="primary"]');
 
   openButton.addEventListener('click', () => drawer.show());
   closeButton.addEventListener('click', () => drawer.hide());
@@ -175,14 +165,9 @@ 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" type="primary" onClick={() => setOpen(false)}>
+        <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
           Close
         </SlButton>
       </SlDrawer>
@@ -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
@@ -205,18 +192,18 @@ By default, the drawer slides out of its [containing block](https://developer.mo
 
   <sl-drawer label="Drawer" contained class="drawer-contained" style="--size: 50%;">
     Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-    <sl-button slot="footer" type="primary">Close</sl-button>
+    <sl-button slot="footer" variant="primary">Close</sl-button>
   </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[type="primary"]');
+  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,17 +226,18 @@ 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%' }}
         >
           Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-          <SlButton slot="footer" type="primary" onClick={() => setOpen(false)}>
+          <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
             Close
           </SlButton>
         </SlDrawer>
@@ -268,7 +256,7 @@ Use the `--size` custom property to set the drawer's size. This will be applied
 ```html preview
 <sl-drawer label="Drawer" class="drawer-custom-size" style="--size: 50vw;">
   This drawer is always 50% of the viewport.
-  <sl-button slot="footer" type="primary">Close</sl-button>
+  <sl-button slot="footer" variant="primary">Close</sl-button>
 </sl-drawer>
 
 <sl-button>Open Drawer</sl-button>
@@ -276,7 +264,7 @@ Use the `--size` custom property to set the drawer's size. This will be applied
 <script>
   const drawer = document.querySelector('.drawer-custom-size');
   const openButton = drawer.nextElementSibling;
-  const closeButton = drawer.querySelector('sl-button[type="primary"]');
+  const closeButton = drawer.querySelector('sl-button[variant="primary"]');
 
   openButton.addEventListener('click', () => drawer.show());
   closeButton.addEventListener('click', () => drawer.hide());
@@ -292,13 +280,9 @@ 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" type="primary" onClick={() => setOpen(false)}>
+        <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
           Close
         </SlButton>
       </SlDrawer>
@@ -318,7 +302,7 @@ By design, a drawer's height will never exceed 100% of its container. As such, d
   <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>
-  <sl-button slot="footer" type="primary">Close</sl-button>
+  <sl-button slot="footer" variant="primary">Close</sl-button>
 </sl-drawer>
 
 <sl-button>Open Drawer</sl-button>
@@ -326,7 +310,7 @@ By design, a drawer's height will never exceed 100% of its container. As such, d
 <script>
   const drawer = document.querySelector('.drawer-scrolling');
   const openButton = drawer.nextElementSibling;
-  const closeButton = drawer.querySelector('sl-button[type="primary"]');
+  const closeButton = drawer.querySelector('sl-button[variant="primary"]');
 
   openButton.addEventListener('click', () => drawer.show());
   closeButton.addEventListener('click', () => drawer.hide());
@@ -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)',
@@ -352,7 +336,55 @@ const App = () => {
         >
           <p>Scroll down and give it a try! 👇</p>
         </div>
-        <SlButton slot="footer" type="primary" onClick={() => setOpen(false)}>
+        <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
+          Close
+        </SlButton>
+      </SlDrawer>
+
+      <SlButton onClick={() => setOpen(true)}>Open Drawer</SlButton>
+    </>
+  );
+};
+```
+
+### 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>
@@ -369,11 +401,12 @@ By default, drawers will close when the user clicks the close button, clicks the
 
 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" type="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>
@@ -381,12 +414,17 @@ To keep the drawer open in such cases, you can cancel the `sl-request-close` eve
 <script>
   const drawer = document.querySelector('.drawer-deny-close');
   const openButton = drawer.nextElementSibling;
-  const closeButton = drawer.querySelector('sl-button[type="primary"]');
+  const closeButton = drawer.querySelector('sl-button[variant="primary"]');
 
   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,16 +435,18 @@ 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.
-        <SlButton slot="footer" type="primary" onClick={() => setOpen(false)}>
+      <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>
       </SlDrawer>
@@ -419,12 +459,12 @@ 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-button slot="footer" type="primary">Close</sl-button>
+  <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>
 
 <sl-button>Open Drawer</sl-button>
@@ -433,45 +473,25 @@ By default, the drawer's panel will gain focus when opened. This allows the firs
   const drawer = document.querySelector('.drawer-focus');
   const input = drawer.querySelector('sl-input');
   const openButton = drawer.nextElementSibling;
-  const closeButton = drawer.querySelector('sl-button[type="primary"]');
+  const closeButton = drawer.querySelector('sl-button[variant="primary"]');
 
   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" />
-        <SlButton slot="footer" type="primary" onClick={() => setOpen(false)}>
+      <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>
       </SlDrawer>
@@ -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>
 );
 ```
 
@@ -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" type="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" type="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" type="text" label="Name" required></sl-input>
-  <sl-input name="age" type="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" type="text" label="Name" required />
-      <SlInput name="age" type="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 type="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 type="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 type="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 type="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 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="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 type="email" label="Email" placeholder="you@example.com" required />
-    <br />
-    <SlInput type="url" label="URL" placeholder="https://example.com/" required />
-    <br />
-    <SlButton type="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 type="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 type="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.
 
-Shoelace comes bundled with over 1,300 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.
+?> 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.
 
-Click or tap on an icon below to copy its name and use it like this.
+## 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>
 ```

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,41 @@ 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: 60px;
+    --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: span 2;
+    padding-left: calc(var(--label-width) + var(--gap-width));
+  }
+</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
@@ -141,7 +88,7 @@ Add content to the start and end of menu items using the `prefix` and `suffix` s
   <sl-menu-item>
     <sl-icon slot="prefix" name="envelope"></sl-icon>
     Messages
-    <sl-badge slot="suffix" type="primary" pill>12</sl-badge>
+    <sl-badge slot="suffix" variant="primary" pill>12</sl-badge>
   </sl-menu-item>
 
   <sl-divider></sl-divider>
@@ -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" type="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-button type="primary">Click to mutate</sl-button>
+  <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 type={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>
@@ -95,7 +92,7 @@ Use the `child-list` attribute to watch for new child elements that are added or
 <div class="mutation-child-list">
   <sl-mutation-observer child-list>
     <div class="buttons">
-      <sl-button type="primary">Add button</sl-button>
+      <sl-button variant="primary">Add button</sl-button>
     </div>
   </sl-mutation-observer>
 
@@ -105,7 +102,7 @@ Use the `child-list` attribute to watch for new child elements that are added or
     const container = document.querySelector('.mutation-child-list');
     const mutationObserver = container.querySelector('sl-mutation-observer');
     const buttons = container.querySelector('.buttons');
-    const button = container.querySelector('sl-button[type="primary"]');
+    const button = container.querySelector('sl-button[variant="primary"]');
     let i = 0;
 
     // Add a button
@@ -117,7 +114,7 @@ Use the `child-list` attribute to watch for new child elements that are added or
 
     // Remove a button
     buttons.addEventListener('click', event => {
-      const target = event.target.closest('sl-button:not([type="primary"])');
+      const target = event.target.closest('sl-button:not([variant="primary"])');
       event.stopPropagation();
 
       if (target) {
@@ -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,21 +168,19 @@ 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 type="primary" onClick={addButton}>Add button</SlButton>
+            <SlButton variant="primary" onClick={addButton}>
+              Add button
+            </SlButton>
             {buttonIds.map(id => (
-              <SlButton key={id} type="default" onClick={() => removeButton(id)}>
+              <SlButton key={id} variant="default" onClick={() => removeButton(id)}>
                 {id}
               </SlButton>
             ))}
           </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>
@@ -20,7 +18,7 @@ QR codes are useful for providing small pieces of information to users who can q
   const input = container.querySelector('sl-input');
 
   input.value = qrCode.value;
-  input.addEventListener('sl-input', () => qrCode.value = input.value);
+  input.addEventListener('sl-input', () => (qrCode.value = input.value));
 </script>
 
 <style>
@@ -79,9 +77,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 +91,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 +105,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-group').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

@@ -0,0 +1,756 @@
+# Split Panel
+
+[component-header:sl-split-panel]
+
+```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;"
+  >
+    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>
+    <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, use the `position` attribute. If no position is provided, it will default to 50% of the available space.
+
+```html preview
+<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;"
+  >
+    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;"
+  >
+    Start
+  </div>
+  <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.
+
+```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;"
+    >
+      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>
+
+  <div class="split-panel-snapping-dots"></div>
+</div>
+
+<style>
+  .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%;
+  }
+</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 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;"
+  >
+    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 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.
+
+Try resizing the example below with each option and notice how the panels respond.
+
+```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;"
+    >
+      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>
+
+  <sl-select label="Primary Panel" value="" style="max-width: 200px; margin-top: 1rem;">
+    <sl-option value="">None</sl-option>
+    <sl-option value="start">Start</sl-option>
+    <sl-option value="end">End</sl-option>
+  </sl-select>
+</div>
+
+<script>
+  const container = document.querySelector('.split-panel-primary');
+  const splitPanel = container.querySelector('sl-split-panel');
+  const select = container.querySelector('sl-select');
+
+  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. If no primary panel is designated, these constraints will be applied to the `start` panel.
+
+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;"
+  >
+    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 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;"
+  >
+    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;"
+      >
+        Top
+      </div>
+      <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>
+  </div>
+</sl-split-panel>
+```
+
+```jsx react
+import { SlSplitPanel } from '@shoelace-style/shoelace/dist/react';
+
+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">
+      <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>
+  </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-divider">
+  <sl-split-panel>
+    <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>
+</div>
+
+<style>
+  .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);
+    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);
+    color: var(--sl-color-neutral-0);
+    padding: .5rem .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);
+  }
+`;
+
+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,27 +2,24 @@
 
 [component-header:sl-tag]
 
-Tags are used as labels to organize things or to indicate a selection.
-
 ```html preview
-<sl-tag type="primary">Primary</sl-tag>
-<sl-tag type="success">Success</sl-tag>
-<sl-tag type="neutral">Neutral</sl-tag>
-<sl-tag type="warning">Warning</sl-tag>
-<sl-tag type="danger">Danger</sl-tag>
+<sl-tag variant="primary">Primary</sl-tag>
+<sl-tag variant="success">Success</sl-tag>
+<sl-tag variant="neutral">Neutral</sl-tag>
+<sl-tag variant="warning">Warning</sl-tag>
+<sl-tag variant="danger">Danger</sl-tag>
 ```
 
-
 ```jsx react
 import { SlTag } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlTag type="primary">Primary</SlTag>
-    <SlTag type="success">Success</SlTag>
-    <SlTag type="neutral">Neutral</SlTag>
-    <SlTag type="warning">Warning</SlTag>
-    <SlTag type="danger">Danger</SlTag> 
+    <SlTag variant="primary">Primary</SlTag>
+    <SlTag variant="success">Success</SlTag>
+    <SlTag variant="neutral">Neutral</SlTag>
+    <SlTag variant="warning">Warning</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 type="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,372 @@
+# 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 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-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 {
+    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) {
+    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) {
+    color: var(--sl-color-danger-700);
+  }
+
+  .validity-styles sl-input:focus-within[data-user-invalid]::part(base),
+  .validity-styles sl-select:focus-within[data-user-invalid]::part(combobox) {
+    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) {
+    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) {
+    color: var(--sl-color-success-700);
+  }
+
+  .validity-styles sl-input:focus-within[data-user-valid]::part(base),
+  .validity-styles sl-select:focus-within[data-user-valid]::part(combobox) {
+    border-color: var(--sl-color-success-600);
+    box-shadow: 0 0 0 var(--sl-focus-ring-width) var(--sl-color-success-300);
+  }
+</style>
+```
+
+## 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

@@ -9,7 +9,7 @@ If you're using a framework, make sure to check out the pages for [React](/frame
 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>
 ```
 
@@ -20,7 +20,7 @@ The easiest way to install Shoelace is with the CDN. Just add the following tags
 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 +29,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 +58,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>
 ```
 
@@ -83,12 +90,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';

docs/getting-started/localization.md

@@ -1,6 +1,6 @@
 # Localization
 
-Components can be localized by importing the appropriate translation file and setting the desired [`lang` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang) on the `<html>` element. Here's an example that renders Shoelace components in Spanish.
+Components can be localized by importing the appropriate translation file and setting the desired [`lang` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang) and/or [`dir` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir) on the `<html>` element. Here's an example that renders Shoelace components in Spanish.
 
 ```html
 <html lang="es">
@@ -16,23 +16,9 @@ Components can be localized by importing the appropriate translation file and se
 
 Through the magic of a mutation observer, changing the `lang` attribute will automatically update all localized components to use the new locale.
 
-?> Shoelace provides a localization mechanism for component internals. This is not designed to be used as localization tool for your entire application. You should use a more appropriate tool such as [i18next](https://www.i18next.com/) if you need to localize content in your app.
-
 ## Available Translations
 
-Shoelace ships with the following translations. The default is English (US), which also serves as the fallback locale. As such, you do not need to import the English translation.
-
-- `en` - English (US)
-- `de-CH` - German (Switzerland)
-- `de` - German
-- `es` - Spanish (Latin America)
-- `fr` - French
-- `he` - Hebrew
-- `ja` - Japanese
-- `nl` - Dutch
-- `pl` - Polish
-- `pt` - Portuguese
-- `ru` - Russian
+Shoelace ships with a number of translations. The default is English (US), which also serves as the fallback locale. As such, you do not need to import the English translation. To see a list of all available translations in the latest version, [refer to this directory](https://github.com/shoelace-style/shoelace/tree/current/src/translations).
 
 The location of translations depends on how you're consuming Shoelace.
 
@@ -67,9 +53,11 @@ Regional translations are welcome! For example, if a German translation (`de`) e
 
 If you have any questions, please start a [discussion](https://github.com/shoelace-style/shoelace/discussions) or ask in the [community chat](https://discord.gg/mg8f26C).
 
+?> Shoelace provides a localization mechanism for component internals. This is not designed to be used as localization tool for your entire application. You should use a more appropriate tool such as [i18next](https://www.i18next.com/) if you need to localize content in your app.
+
 ## Multiple Locales Per Page
 
-You can use a different locale for an individual component by setting its `lang` attribute. Here's a contrived example to demonstrate.
+You can use a different locale for an individual component by setting its `lang` and/or `dir` attributes. Here's a contrived example to demonstrate.
 
 ```html
 <html lang="es">
@@ -82,7 +70,7 @@ You can use a different locale for an individual component by setting its `lang`
 </html>
 ```
 
-For performance reasons, the `lang` attribute must be on the component itself, not on an ancestor element.
+For performance reasons, the `lang` and `dir` attributes must be on the component itself, not on an ancestor element.
 
 ```html
 <html lang="es">

docs/getting-started/overview.md

@@ -2,7 +2,7 @@
 <div class="splash-start">
 <img class="splash-logo" src="/assets/images/wordmark.svg" alt="Shoelace">
 
-# <span hidden>Shoelace:</span> A forward-thinking library of web components.
+# <sl-visually-hidden>Shoelace:</sl-visually-hidden> A forward-thinking library of web components.
 
 - Works with all frameworks 🧩
 - Works with CDNs 🚛
@@ -14,6 +14,7 @@
 - Open source 😸
 
 Designed in New Hampshire by [Cory LaViska](https://twitter.com/claviska).
+
 </div>
 <div class="splash-end">
 <img class="splash-image" src="/assets/images/undraw-content-team.svg" alt="Cartoon of people assembling components while standing on a giant laptop.">
@@ -32,7 +33,7 @@ Designed in New Hampshire by [Cory LaViska](https://twitter.com/claviska).
 Add the following code to your page.
 
 ```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>
 ```
 
@@ -44,7 +45,6 @@ Now you have access to all of Shoelace's components! Try adding a button:
 
 ?> This will load all of Shoelace's components, but you should probably only load the ones you're actually using. To learn how, or for other ways to install Shoelace, refer to the [installation instructions](getting-started/installation).
 
-
 ## New to Web Components?
 
 **TL;DR** – we finally have a way to create [our own HTML elements](https://html.spec.whatwg.org/multipage/custom-elements.html) and use them in any framework we want!
@@ -73,11 +73,11 @@ With Shoelace, you can:
 - Incrementally adopt components as needed (no need to ditch your framework)
 - Upgrade or switch frameworks without rebuilding foundational components
 
-If your organization is looking to build a design system, [Shoelace will save you thousands of dollars](https://medium.com/eightshapes-llc/and-you-thought-buttons-were-easy-26eb5b5c1871).* All the foundational components you need are right here, ready to be customized for your brand. And since it's built on web standards, browsers will continue to support it for many years to come.
+If your organization is looking to build a design system, [Shoelace will save you thousands of dollars](https://medium.com/eightshapes-llc/and-you-thought-buttons-were-easy-26eb5b5c1871).\* All the foundational components you need are right here, ready to be customized for your brand. And since it's built on web standards, browsers will continue to support it for many years to come.
 
 Whether you use Shoelace as a starting point for your organization's design system or for a fun personal project, there's no limit to what you can do with it.
 
-<small>*Please consider giving back some of what you save by [supporting this project with a sponsorship](https://github.com/sponsors/claviska).</small>
+<small>\*Please consider giving back some of what you save by [supporting this project with a sponsorship](https://github.com/sponsors/claviska).</small>
 
 ## Browser Support
 
@@ -106,7 +106,7 @@ Designing, developing, and supporting this library requires a lot of time, effor
 </sl-button>
 
 <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> <span class="github-star-count">Star</span>
+  <sl-icon slot="prefix" name="github"></sl-icon> Star
 </sl-button>
 
 <sl-button class="repo-button repo-button--twitter" href="https://twitter.com/shoelace_style" target="_blank">
@@ -117,14 +117,14 @@ Designing, developing, and supporting this library requires a lot of time, effor
 
 Special thanks to the following projects and individuals that help make Shoelace possible.
 
-- Components are built with [LitElement](https://lit-element.polymer-project.org/)
+- Components are built with [Lit](https://lit.dev/)
 - Component metadata is generated by the [Custom Elements Manifest Analyzer](https://github.com/open-wc/custom-elements-manifest)
 - Documentation is powered by [Docsify](https://docsify.js.org/)
 - CDN services are provided by [jsDelivr](https://www.jsdelivr.com/)
 - Color primitives are inspired by [Tailwind](https://tailwindcss.com/)
 - Icons are courtesy of [Bootstrap Icons](https://icons.getbootstrap.com/)
 - The homepage illustration is courtesy of [unDraw](https://undraw.co/)
-- Positioning of menus, tooltips, et al is handled by [Popper.js](https://popper.js.org/)
+- Positioning of dropdowns, tooltips, et al is handled by [Floating UI](https://floating-ui.com/)
 - Animations are courtesy of [animate.css](https://animate.style/)
 - QR codes are generated with [qr-creator](https://github.com/nimiq/qr-creator)
 - Search is powered by [Lunr](https://lunrjs.com/)

docs/getting-started/themes.md

@@ -8,7 +8,7 @@ A theme is nothing more than a stylesheet that uses the Shoelace API to define d
 
 ## Theme Basics
 
-All themes are scoped to classes using the `sl-theme-{name}` convention, where `{name}` is a lowercase, hyphen-delimited value representing the name of the theme. The included light and dark themes use `sl-theme-light` and `sl-theme-dark`, respectively. A custom theme called "Purple Power", for example, would use a class called `sl-theme-purple-power` 
+All themes are scoped to classes using the `sl-theme-{name}` convention, where `{name}` is a lowercase, hyphen-delimited value representing the name of the theme. The included light and dark themes use `sl-theme-light` and `sl-theme-dark`, respectively. A custom theme called "Purple Power", for example, would use a class called `sl-theme-purple-power`
 
 All selectors must be scoped to the theme's class to ensure interoperability with other themes. You should also scope them to `:host` so they can be imported and applied to custom element shadow roots.
 
@@ -26,7 +26,7 @@ To activate a theme, import it and apply the theme's class to the `<html>` eleme
 ```html
 <html class="sl-theme-dark">
   <head>
-    <link rel="stylesheet" href="path/to/shoelace/dist/themes/dark.css">
+    <link rel="stylesheet" href="path/to/shoelace/dist/themes/dark.css" />
   </head>
 
   <body>
@@ -44,15 +44,15 @@ You can activate themes on various containers throughout the page. This example
 ```html
 <html>
   <head>
-    <link rel="stylesheet" href="path/to/shoelace/dist/themes/light.css">
-    <link rel="stylesheet" href="path/to/shoelace/dist/themes/dark.css">
+    <link rel="stylesheet" href="path/to/shoelace/dist/themes/light.css" />
+    <link rel="stylesheet" href="path/to/shoelace/dist/themes/dark.css" />
   </head>
 
   <body>
     <nav class="sl-theme-dark">
       <!-- dark-themed sidebar -->
     </nav>
-    
+
     <!-- light-themed content -->
   </body>
 </html>
@@ -71,8 +71,8 @@ The easiest way to customize Shoelace is to override one of the built-in themes.
 If you're customizing the light theme, you should scope your styles to the following selectors.
 
 ```css
-:root, 
-:host, 
+:root,
+:host,
 .sl-theme-light {
   /* your custom styles here */
 }
@@ -117,7 +117,7 @@ The dark theme works by taking the light theme's [color tokens](/tokens/color) a
 To install the dark theme, add the following to the `<head>` section of your 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" />
 ```
 
 To activate the theme, apply the `sl-theme-dark` class to the `<html>` element.

docs/getting-started/usage.md

@@ -2,9 +2,9 @@
 
 Shoelace components are just regular HTML elements, or [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) to be precise. You can use them like any other element. Each component has detailed documentation that describes its full API, including properties, events, methods, and more.
 
-If you're new to custom elements, often referred to as "web components," this section will familiarize you with how to use them. 
+If you're new to custom elements, often referred to as "web components," this section will familiarize you with how to use them.
 
-## Properties
+## Attributes & Properties
 
 Many components have properties that can be set using attributes. For example, buttons accept a `size` attribute that maps to the `size` property which dictates the button's size.
 
@@ -18,7 +18,7 @@ Some properties are boolean, so they only have true/false values. To activate a
 <sl-button disabled>Click me</sl-button>
 ```
 
-In rare cases, a property may require an array, an object, or a function. For example, to customize the color picker's list of preset swatches, you set the `swatches` property to an array of colors. This can be done with JavaScript.
+In rare cases, a property may require an array, an object, or a function. For example, to customize the color picker's list of preset swatches, you set the `swatches` property to an array of colors. This must be done with JavaScript.
 
 ```html
 <sl-color-picker></sl-color-picker>
@@ -106,15 +106,88 @@ For example, `<button>` and `<sl-button>` both have a `type` attribute, but it d
 
 ?> **Don't make assumptions about a component's API!** To prevent unexpected behaviors, please take the time to review the documentation and make sure you understand what each attribute, property, method, and event is intended to do.
 
+## Waiting for Components to Load
+
+Web components are registered with JavaScript, so depending on how and when you load Shoelace, you may notice a [Flash of Undefined Custom Elements (FOUCE)](https://www.abeautifulsite.net/posts/flash-of-undefined-custom-elements/) when the page loads. There are a couple ways to prevent this, both of which are described in the linked article.
+
+One option is to use the [`:defined`](https://developer.mozilla.org/en-US/docs/Web/CSS/:defined) CSS pseudo-class to "hide" custom elements that haven't been registered yet. You can scope it to specific tags or you can hide all undefined custom elements as shown below.
+
+```css
+:not(:defined) {
+  visibility: hidden;
+}
+```
+
+As soon as a custom element is registered, it will immediately appear with all of its styles, effectively eliminating FOUCE. Note the use of `visibility: hidden` instead of `display: none` to reduce shifting as elements are registered. The drawback to this approach is that custom elements can potentially appear one by one instead of all at the same time.
+
+Another option is to use [`customElements.whenDefined()`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/whenDefined), which returns a promise that resolves when the specified element gets registered. You'll probably want to use it with [`Promise.allSettled()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled) in case an element fails to load for some reason.
+
+A clever way to use this method is to hide the `<body>` with `opacity: 0` and add a class that fades it in as soon as all your custom elements are defined.
+
+```html
+<style>
+  body {
+    opacity: 0;
+  }
+
+  body.ready {
+    opacity: 1;
+    transition: 0.25s opacity;
+  }
+</style>
+
+<script type="module">
+  await Promise.allSettled([
+    customElements.whenDefined('sl-button'),
+    customElements.whenDefined('sl-card'),
+    customElements.whenDefined('sl-rating')
+  ]);
+
+  // Button, card, and rating are registered now! Add
+  // the `ready` class so the UI fades in.
+  document.body.classList.add('ready');
+</script>
+```
+
+## Component Rendering and Updating
+
+Shoelace components are built with [Lit](https://lit.dev/), a tiny library that makes authoring custom elements easier, more maintainable, and a lot of fun! As a Shoelace user, here is some helpful information about rendering and updating you should probably be aware of.
+
+To optimize performance and reduce re-renders, Lit batches component updates. This means changing multiple attributes or properties at the same time will result in just a single re-render. In most cases, this isn't an issue, but there may be times you'll need to wait for the component to update before continuing.
+
+Consider this example. We're going to change the `checked` property of the checkbox and observe its corresponding `checked` attribute, which happens to reflect.
+
+```js
+const checkbox = document.querySelector('sl-checkbox');
+checkbox.checked = true;
+
+console.log(checkbox.hasAttribute('checked')); // false
+```
+
+Most devs will expect this to be `true` instead of `false`, but the component hasn't had a chance to re-render yet so the attribute doesn't exist when `hasAttribute()` is called. Since changes are batched, we need to wait for the update before proceeding. This can be done using the `updateComplete` property, which is available on all Lit-based components.
+
+```js
+const checkbox = document.querySelector('sl-checkbox');
+checkbox.checked = true;
+
+checkbox.updateComplete.then(() => {
+  console.log(checkbox.hasAttribute('checked')); // true
+});
+```
+
+This time we see an empty string, which means the boolean attribute is now present!
+
+?> Avoid using `setTimeout()` or `requestAnimationFrame()` in situations like this. They might work, but it's far more reliable to use `updateComplete` instead.
+
 ## Code Completion
 
 ### VS Code
 
-Shoelace ships with a file called `vscode.html-custom-data.json` that can be used to describe its components to Visual Studio Code. This enables code completion for Shoelace components (also known as "code hinting" or "IntelliSense"). To enable it, you need to tell VS Code where the file is.
+Shoelace ships with a file called `vscode.html-custom-data.json` that can be used to describe it's custom elements to Visual Studio Code. This enables code completion for Shoelace components (also known as "code hinting" or "IntelliSense"). To enable it, you need to tell VS Code where the file is.
 
 1. [Install Shoelace locally](/getting-started/installation#local-installation)
-2. Create a folder called `.vscode` at the root of your project
-3. Create a file inside the folder called `settings.json`
+2. If it doesn't already exist, create a folder called `.vscode` at the root of your project
+3. If it doesn't already exist, create a file inside that folder called `settings.json`
 4. Add the following to the file
 
 ```js

docs/index.html

@@ -9,7 +9,7 @@
       content="Shoelace provides a collection of professionally designed, every day UI components built on a framework-agnostic technology."
     />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <meta name="custom-elements-manifest" content="dist/custom-elements.json" />
+    <meta name="custom-elements-manifest" content="/dist/custom-elements.json" />
     <meta property="og:title" content="Shoelace" />
     <meta
       property="og:description"
@@ -62,7 +62,6 @@
         },
         coverpage: false,
         executeScript: true,
-        ga: 'UA-6412891-16',
         homepage: '/getting-started/overview.md',
         loadSidebar: true,
         logo: '/assets/images/wordmark.svg',
@@ -82,7 +81,6 @@
       };
     </script>
     <script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js"></script>
-    <script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/plugins/ga.min.js"></script>
     <script src="https://cdn.jsdelivr.net/npm/docsify-copy-code@2"></script>
     <script src="https://cdn.jsdelivr.net/npm/docsify-pagination@2/dist/docsify-pagination.min.js"></script>
     <script src="https://cdn.jsdelivr.net/npm/prismjs@1.25.0/components/prism-bash.min.js"></script>

docs/resources/accessibility.md

@@ -15,4 +15,4 @@ I’m fully aware that I may not get it right every time for every user, so I in
 This is the path forward. Together, we will continue to make Shoelace accessible to as many users as possible.
 
 — Cory LaViska<br>
-_Creator of Shoelace_
+_Creator of Shoelace_

docs/resources/changelog.md

@@ -1,10 +1,575 @@
 # Changelog
 
-Shoelace follows [Semantic Versioning](https://semver.org/). Breaking changes in components with the <sl-badge type="primary" pill>Stable</sl-badge> badge will not be accepted until the next major version. As such, all contributions must consider the project's roadmap and take this into consideration. Features that are deemed no longer necessary will be deprecated but not removed.
+Shoelace follows [Semantic Versioning](https://semver.org/). Breaking changes in components with the <sl-badge variant="primary" pill>Stable</sl-badge> badge will not be accepted until the next major version. As such, all contributions must consider the project's roadmap and take this into consideration. Features that are deemed no longer necessary will be deprecated but not removed.
 
-Components with the <sl-badge type="warning" pill>Experimental</sl-badge> badge should not be used in production. They are made available as release candidates for development and testing purposes. As such, changes to experimental components will not be subject to semantic versioning.
+Components with the <sl-badge variant="warning" pill>Experimental</sl-badge> badge should not be used in production. They are made available as release candidates for development and testing purposes. As such, changes to experimental components will not be subject to semantic versioning.
 
-_During the beta period, these restrictions may be relaxed in the event of a mission-critical bug._ 🐛
+New versions of Shoelace are released as-needed and generally occur when a critical mass of changes have accumulated. At any time, you can see what's coming in the next release by visiting [next.shoelace.style](https://next.shoelace.style).
+
+## 2.0.0
+
+This is the first stable release of Shoelace 2, meaning breaking changes to the API will no longer be accepted for this version. Development of Shoelace 2.0 started in January 2020. The first beta was released on [July 15, 2020](https://github.com/shoelace-style/shoelace/releases/tag/v2.0.0-beta.1). Since then, Shoelace has grown quite a bit! Here are some stats from the project as of January 24, 2023:
+
+- 55 components have been built
+- [Over 2,500 commits](https://github.com/shoelace-style/shoelace/commits/next) have been made to the project
+- [85 people](https://github.com/shoelace-style/shoelace/graphs/contributors) have contributed to the project
+- [669 issues](https://github.com/shoelace-style/shoelace/issues?q=is%3Aissue+is%3Aclosed) have been filed on GitHub
+- [274 pull requests](https://github.com/shoelace-style/shoelace/pulls) have been opened
+- [More than 150 discussions](https://github.com/shoelace-style/shoelace/discussions) have been started on GitHub
+- [Over 500 people](https://discord.com/invite/mg8f26C) have joined the Shoelace community on Discord
+- [Over 300 million CDN hits](https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace) per month
+- [Over 13,000 npm downloads](https://www.npmjs.com/package/@shoelace-style/shoelace) per week
+- [73rd most popular project](https://www.jsdelivr.com/statistics) on jsDelivr
+- [#2 product of the day](https://www.producthunt.com/products/shoelace-css) on Product Hunt (July 25, 2020)
+
+I'd like to extend a very special thank you to every single contributor who worked to make this possible. Everyone who's filed a bug, submitted a PR, requested a feature, started a discussion, helped with testing, and advocated for the project. You are just as responsible for Shoelace's success as I am. I'd also like to thank the folks at [Font&nbsp;Awesome](https://fontawesome.com/) for recognizing Shoelace's potential and [believing in me](https://blog.fontawesome.com/shoelace-joins-font-awesome/) to make it happen.
+
+Thank you! And keep building _awesome_ stuff!
+
+Without further ado, here are the notes for this release.
+
+- Added support for the `inert` attribute on `<sl-menu-item>` to allow hidden menu items to not accept focus [#1107](https://github.com/shoelace-style/shoelace/issues/1107)
+- Added the `tag` part to `<sl-select>`
+- Added `sl-hover` event to `<sl-rating>` [#1125](https://github.com/shoelace-style/shoelace/issues/1125)
+- Added the `@documentation` tag with a link to the docs for each component
+- Added the `form` attribute to all form controls to allow placing them outside of a `<form>` element [#1130](https://github.com/shoelace-style/shoelace/issues/1130)
+- Added the `getFormControls()` function as an alternative to `HTMLFormElement.elements`
+- Added missing docs for the `header-actions` slot in `<sl-dialog>` and `<sl-drawer>`
+- Added `hue-slider-handle` and `opacity-slider-handle` parts to `<sl-color-picker>` and correct other part names in the docs [#1142](https://github.com/shoelace-style/shoelace/issues/1142)
+- Fixed a bug in `<sl-select>` that prevented placeholders from showing when `multiple` was used [#1109](https://github.com/shoelace-style/shoelace/issues/1109)
+- Fixed a bug in `<sl-select>` that caused tags to not be rounded when using the `pill` attribute [#1117](https://github.com/shoelace-style/shoelace/issues/1117)
+- Fixed a bug in `<sl-select>` where the `sl-change` and `sl-input` events didn't weren't emitted when removing tags [#1119](https://github.com/shoelace-style/shoelace/issues/1119)
+- Fixed a bug in `<sl-select>` that caused the listbox to scroll to the first selected item when selecting multiple items [#1138](https://github.com/shoelace-style/shoelace/issues/1138)
+- Fixed a bug in `<sl-select>` where the input color and input hover color wasn't using the correct design tokens [#1143](https://github.com/shoelace-style/shoelace/issues/1143)
+- Fixed a bug in `<sl-color-picker>` that logged a console error when parsing swatches with whitespace
+- Fixed a bug in `<sl-color-picker>` that caused selected colors to be wrong due to incorrect HSV calculations
+- Fixed a bug in `<sl-color-picker>` that prevented the initial value from being set correct when assigned as a property [#1141](https://github.com/shoelace-style/shoelace/issues/1141)
+- Fixed a bug in `<sl-radio-button>` that caused the checked button's right border to be incorrect [#1110](https://github.com/shoelace-style/shoelace/issues/1110)
+- Fixed a bug in `<sl-spinner>` that caused the animation to stop working correctly in Safari [#1121](https://github.com/shoelace-style/shoelace/issues/1121)
+- Fixed a bug that prevented the entire `<sl-tab-panel>` to be hidden when inactive
+- Fixed a bug that caused the value of `<sl-radio-group>` to be `undefined` depending on where the radio was activated [#1134](https://github.com/shoelace-style/shoelace/issues/1134)
+- Fixed a bug that caused body content to shift when scroll locking was enabled [#1132](https://github.com/shoelace-style/shoelace/issues/1132)
+- Fixed a bug in `<sl-icon>` that caused icons to sometimes be clipped in Safari
+- Fixed a bug that prevented label colors from inheriting by default in `<sl-checkbox>`, `<sl-radio>`, and `<sl-switch>`
+- Fixed a bug in `<sl-radio-group>` that caused an extra margin between the host element and the internal fieldset [#1139](https://github.com/shoelace-style/shoelace/issues/1139)
+- Refactored the `ShoelaceFormControl` interface to remove the `invalid` property, allowing a more intuitive API for controlling validation internally
+- Renamed the internal `FormSubmitController` to `FormControlController` to better reflect what it's used for
+- Updated Lit to 2.6.1
+- Updated Floating UI to 1.1.0
+- Updated all other dependencies to latest versions
+
+## 2.0.0-beta.88
+
+This release includes a complete rewrite of `<sl-select>` to improve accessibility and simplify its internals.
+
+- 🚨 BREAKING: rewrote `<sl-select>`
+  - Accessibility has been significantly improved, especially in screen readers
+  - You must use `<sl-option>` instead of `<sl-menu-item>` for options now
+  - The `suffix` slot was removed because it was confusing to users and its position made the clear button inaccessible
+  - The `max-tags-visible` attribute has been renamed to `max-options-visible`
+  - Many parts have been removed or renamed (please see the docs for more details)
+- 🚨 BREAKING: removed the `sl-label-change` event from `<sl-menu-item>` (listen for `slotchange` instead)
+- 🚨 BREAKING: removed type to select logic from `<sl-menu>` (this was added specifically for `<sl-select>` which no longer uses `<sl-menu>`)
+- 🚨 BREAKING: swatches in `<sl-color-picker>` are no longer present by default (but you can set them using the `swatches` attribute now)
+- 🚨 BREAKING: improved the accessibility of `<sl-menu-item>` so checked items are announced as such
+  - Checkbox menu items must now have `type="checkbox"` before applying the `checked` attribute
+  - Checkbox menu items will now toggle their `checked` state on their own when selected
+  - Disabled menu items will now receive focus, but are still not selectable
+- Added the `<sl-option>` component
+- Added Traditional Chinese translation [#1086](https://github.com/shoelace-style/shoelace/pull/1086)
+- Added support for `swatches` to be an attribute of `<sl-color-picker>` so swatches can be defined declaratively (it was previously a property; use a `;` to separate color values)
+- Fixed a bug in `<sl-tree-item>` where the checked/indeterminate states could get out of sync when using the `multiple` option [#1076](https://github.com/shoelace-style/shoelace/issues/1076)
+- Fixed a bug in `<sl-tree>` that caused `sl-selection-change` to emit before the DOM updated [#1096](https://github.com/shoelace-style/shoelace/issues/1096)
+- Fixed a bug that prevented `<sl-switch>` from submitting a default value of `on` when no value was provided [#1103](https://github.com/shoelace-style/shoelace/discussions/1103)
+- Fixed a bug in `<sl-textarea>` that caused the scrollbar to show sometimes when using `resize="auto"`
+- Fixed a bug in `<sl-input>` and `<sl-textarea>` that caused its validation states to be out of sync in some cases [#1063](https://github.com/shoelace-style/shoelace/issues/1063)
+- Reorganized all components to make class structures more consistent
+- Updated some incorrect default values for design tokens in the docs [#1097](https://github.com/shoelace-style/shoelace/issues/1097)
+- Updated non-public fields to use the `private` keyword (these were previously private only by convention, but now TypeScript will warn you)
+- Updated the hover style of `<sl-menu-item>` to be consistent with `<sl-option>`
+- Updated the status of `<sl-tree>` and `<sl-tree-item>` from experimental to stable
+- Updated React wrappers to use the latest API from `@lit-labs/react` [#1090](https://github.com/shoelace-style/shoelace/pull/1090)
+- Updated Bootstrap Icons to 1.10.3
+
+## 2.0.0-beta.87
+
+- 🚨 BREAKING: changed the default size of medium checkboxes, radios, and switches to 18px instead of 16px
+- 🚨 BREAKING: renamed the `--sl-toggle-size` design token to `--sl-toggle-size-medium`
+- Added the `--sl-toggle-size-small` and `--sl-toggle-size-large` design tokens
+- Added the `size` attribute to `<sl-checkbox>`, `<sl-radio>`, and `<sl-switch>` [#1071](https://github.com/shoelace-style/shoelace/issues/1071)
+- Added the `sl-input` event to `<sl-checkbox>`, `<sl-color-picker>`, `<sl-radio>`, `<sl-range>`, and `<sl-switch>`
+- Added HSV format to `<sl-color-picker>` [#1072](https://github.com/shoelace-style/shoelace/pull/1072)
+- Fixed a bug in `<sl-color-picker>` that sometimes prevented the color from updating when clicking or tapping on the controls
+- Fixed a bug in `<sl-color-picker>` that prevented text from being entered in the color input
+- Fixed a bug in `<sl-input>` that caused the `sl-change` event to be incorrectly emitted when the value was set programmatically [#917](https://github.com/shoelace-style/shoelace/issues/917)
+- Fixed a bug in `<sl-input>` and `<sl-textarea>` that made it impossible to disable spell checking [#1061](https://github.com/shoelace-style/shoelace/issues/1061)
+- Fixed non-modal behaviors in `<sl-drawer>` when using the `contained` attribute [#1051](https://github.com/shoelace-style/shoelace/issues/1051)
+- Fixed a bug in `<sl-checkbox>` and `<sl-radio>` that caused the checked icons to not scale property when resized
+- Fixed a bug that broke React imports [#1050](https://github.com/shoelace-style/shoelace/pull/1050)
+- Refactored `<sl-color-picker>` to use `@ctrl/tinycolor` instead of `color` saving ~67KB [#1072](https://github.com/shoelace-style/shoelace/pull/1072)
+- Removed the `formdata` event polyfill since it's now available in the last two versions of all major browsers
+
+## 2.0.0-beta.86
+
+- 🚨 BREAKING: changed the default value of `date` in `<sl-relative-time>` to the current date instead of the Unix epoch
+- 🚨 BREAKING: removed the `handle-icon` part and slot from `<sl-image-comparer>` (use `handle` instead)
+- 🚨 BREAKING: removed the `handle` slot from `<sl-split-panel>` (use the `divider` slot instead)
+- 🚨 BREAKING: removed the `--box-shadow` custom property from `<sl-alert>` (apply a box shadow to `::part(base)` instead)
+- 🚨 BREAKING: removed the `play-icon` and `pause-icon` parts (use the `play-icon` and `pause-icon` slots instead)
+- Added `header-actions` slot to `<sl-dialog>` and `<sl-drawer>`
+- Added the `expand-icon` and `collapse-icon` slots to `<sl-details>` and refactored the icon animation [#1046](https://github.com/shoelace-style/shoelace/discussions/1046)
+- Added the `play-icon` and `pause-icon` slots to `<sl-animated-image>` so you can customize the default icons
+- Converted `isTreeItem()` export to a static method of `<sl-tree-item>`
+- Fixed a bug in `<sl-tree-item>` where `sl-selection-change` was emitted when the selection didn't change [#1030](https://github.com/shoelace-style/shoelace/pull/1030)
+- Fixed a bug in `<sl-button-group>` that caused the border to render incorrectly when hovering over icons inside buttons [#1035](https://github.com/shoelace-style/shoelace/issues/1035)
+- Fixed an incorrect default for `flip-fallback-strategy` in `<sl-popup>` that caused the fallback strategy to be `initial` instead of `best-fit`, which is inconsistent with Floating UI's default [#1036](https://github.com/shoelace-style/shoelace/issues/1036)
+- Fixed a bug where browser validation tooltips would show up when hovering over form controls [#1037](https://github.com/shoelace-style/shoelace/issues/1037)
+- Fixed a bug in `<sl-tab-group>` that sometimes caused the active tab indicator to not animate
+- Fixed a bug in `<sl-tree-item>` that caused the expand/collapse icon slot to be out of sync when the node is open initially
+- Fixed the mislabeled `handle-icon` slot in `<sl-image-comparer>` (it now points to the `<slot>`, not the slot's fallback content)
+- Fixed the border radius in `<sl-dropdown>` so it matches with nested `<sl-menu>` elements
+- Fixed a bug that caused all button values to appear in submitted form data even if they weren't the submitter
+- Improved IntelliSense in VS Code, courtesy of [Burton's amazing CEM Analyzer plugin](https://github.com/break-stuff/cem-plugin-vs-code-custom-data-generator)
+- Improved accessibility of `<sl-alert>` so the alert is announced and the close button has a label
+- Improved accessibility of `<sl-progress-ring>` so slotted labels are announced along with visually hidden labels
+- Refactored all styles and animations to use `translate`, `rotate`, and `scale` instead of `transform`
+- Removed slot wrappers from many components, allowing better control over user-applied styles
+- Removed unused aria attributes from `<sl-skeleton>`
+- Replaced the `x` icon in the system icon library with `x-lg` to improve icon consistency
+
+## 2.0.0-beta.85
+
+- Fixed a bug in `<sl-dropdown>` that caused containing dialogs, drawers, etc. to close when pressing <kbd>Escape</kbd> while focused [#1024](https://github.com/shoelace-style/shoelace/issues/1024)
+- Fixed a bug in `<sl-tree-item>` that allowed lazy nodes to be incorrectly selected [#1023](https://github.com/shoelace-style/shoelace/pull/1023)
+- Fixed a typing bug in `<sl-tree-item>` [#1026](https://github.com/shoelace-style/shoelace/pull/1026)
+- Updated Floating UI to 1.0.7 to fix a bug that prevented `hoist` from working correctly in `<sl-dropdown>` after a recent update [#1024](https://github.com/shoelace-style/shoelace/issues/1024)
+
+## 2.0.0-beta.84
+
+- 🚨 BREAKING: Removed the `fieldset` property from `<sl-radio-group>` (use CSS parts if you want to keep the border) [#965](https://github.com/shoelace-style/shoelace/issues/965)
+- 🚨 BREAKING: Removed `base` and `label` parts from `<sl-radio-group>` (use `form-control` and `form-control__label` instead) [#965](https://github.com/shoelace-style/shoelace/issues/965)
+- 🚨 BREAKING: Removed the `base` part from `<sl-icon>` (style the host element directly instead)
+- 🚨 BREAKING: Removed the `invalid` attribute from form controls (use `[data-invalid]` to target it with CSS)
+- Added validation states to all form controls to allow styling based on various validation states [#1011](https://github.com/shoelace-style/shoelace/issues/1011)
+  - `data-required` - indicates that a value is required
+  - `data-optional` - indicates that a value is NOT required
+  - `data-invalid` - indicates that the form control is invalid
+  - `data-valid` - indicates that the form control is valid
+  - `data-user-invalid` - indicates the form control is invalid and the user has interacted with it
+  - `data-user-valid` - indicates the form control is valid and the user has interacted with it
+- Added npm exports [#1020](https://github.com/shoelace-style/shoelace/pull/1020)
+- Added `checkValidity()` method to all form controls
+- Added `reportValidity()` method to `<sl-range>`
+- Added `button--checked` to `<sl-radio-button>` and `control--checked` to `<sl-radio>` to style just the checked state [#933](https://github.com/shoelace-style/shoelace/pull/933)
+- Added tests for `<sl-menu>`, `<sl-menu-item>`, `<sl-menu-label>`, `<sl-rating>`, `<sl-relative-time>`, `<sl-skeleton>`, `<sl-tab-panel>` and `<sl-tag>` [#935](https://github.com/shoelace-style/shoelace/pull/935)
+  [#949](https://github.com/shoelace-style/shoelace/pull/949) [#951](https://github.com/shoelace-style/shoelace/pull/951) [#953](https://github.com/shoelace-style/shoelace/pull/953)
+  [#956](https://github.com/shoelace-style/shoelace/pull/956) [#984](https://github.com/shoelace-style/shoelace/pull/984) [#991](https://github.com/shoelace-style/shoelace/pull/991)
+- Added translations for Hungarian, Turkish, English (United Kingdom) and German (Austria) [#982](https://github.com/shoelace-style/shoelace/pull/982) [#989](https://github.com/shoelace-style/shoelace/pull/989)
+- Added `--indicator-transition-duration` custom property to `<sl-progress-ring>` [#986](https://github.com/shoelace-style/shoelace/issues/986)
+- Added `--sl-input-required-content-color` custom property to all form controls [#948](https://github.com/shoelace-style/shoelace/pull/948)
+- Added the ability to cancel `sl-show` and `sl-hide` events in `<sl-details>` [#993](https://github.com/shoelace-style/shoelace/issues/993)
+- Added `focus()` and `blur()` methods to `<sl-radio-button>`
+- Added `stepUp()` and `stepDown()` methods to `<sl-input>` and `<sl-range>` [#1013](https://github.com/shoelace-style/shoelace/pull/1013)
+- Added `showPicker()` method to `<sl-input>` [#1013](https://github.com/shoelace-style/shoelace/pull/1013)
+- Added the `handle-icon` part to `<sl-image-comparer>`
+- Added `caret`, `check`, `grip-vertical`, `indeterminate`, and `radio` icons to the system library and removed `check-lg` [#985](https://github.com/shoelace-style/shoelace/issues/985)
+- Added the `loading` attribute to `<sl-avatar>` to allow lazy loading of image avatars [#1006](https://github.com/shoelace-style/shoelace/pull/1006)
+- Added `formenctype` attribute to `<sl-button>` [#1009](https://github.com/shoelace-style/shoelace/pull/1009)
+- Added `exports` to `package.json` and removed the `main` and `module` properties [#1007](https://github.com/shoelace-style/shoelace/pull/1007)
+- Fixed a bug in `<sl-card>` that prevented the border radius to apply correctly to the header [#934](https://github.com/shoelace-style/shoelace/pull/934)
+- Fixed a bug in `<sl-button-group>` where the inner border disappeared on focus [#980](https://github.com/shoelace-style/shoelace/pull/980)
+- Fixed a bug that caused prefix/suffix animations in `<sl-input>` to wobble [#996](https://github.com/shoelace-style/shoelace/issues/996)
+- Fixed a bug in `<sl-icon>` that prevented color from being set on the host element [#999](https://github.com/shoelace-style/shoelace/issues/999)
+- Fixed a bug in `<sl-dropdown>` where the `keydown` event erroneously propagated to ancestors when pressing <kbd>Escape</kbd> [#990](https://github.com/shoelace-style/shoelace/issues/990)
+- Fixed a bug that prevented arrow keys from scrolling content within `<sl-dialog>` and `<sl-drawer>` [#925](https://github.com/shoelace-style/shoelace/issues/925)
+- Fixed a bug that prevented <kbd>Escape</kbd> from closing `<sl-dialog>` and `<sl-drawer>` in some cases
+- Fixed a bug that caused forms to submit unexpectedly when selecting certain characters [#988](https://github.com/shoelace-style/shoelace/pull/988)
+- Fixed a bug in `<sl-radio-group>` that prevented the `invalid` property from correctly reflecting validity sometimes [#992](https://github.com/shoelace-style/shoelace/issues/992)
+- Fixed a bug in `<sl-tree>` that prevented selections from working correctly on dynamically added tree items [#963](https://github.com/shoelace-style/shoelace/issues/963)
+- Fixed module paths in `custom-elements.json` so they point to the dist file instead of the source file [#725](https://github.com/shoelace-style/shoelace/issues/725)
+- Fixed an incorrect return value for `reportValidity()` in `<sl-color-picker>`
+- Improved `<sl-badge>` to improve padding and render relative to the current font size
+- Improved how many components display in forced-colors mode / Windows High Contrast mode
+  - Improved `<sl-color-picker>` so it's usable in forced-colors mode
+  - Improved `<sl-dialog>` and `<sl-drawer>` so the panel is more visible in forced-colors mode
+  - Improved `<sl-menu-item>` so selections are visible in forced-colors mode
+  - Improved `<sl-progress-bar>` so it's visible in forced-colors mode
+  - Improved `<sl-radio-button>` so checked states are visible in forced-colors mode
+  - Improved `<sl-range>` so the thumb, track, and tooltips are visible in forced-colors mode
+  - Improved `<sl-rating>` so icons are visible in forced-colors mode
+  - Improved `<sl-split-panel>` so the divider is visible in forced-colors mode
+  - Improved `<sl-tree-item>` so selected items are visible in forced-colors mode
+  - Improved `<sl-tab-group>` so tabs are cleaner and easier to understand in forced-colors mode
+- Improved positioning of the menu in `<sl-select>` so you can customize the menu width [#1018](https://github.com/shoelace-style/shoelace/issues/1018)
+- Moved all component descriptions to `@summary` to get them within documentation tools [#962](https://github.com/shoelace-style/shoelace/pull/962)
+- Refactored form controls to use the `ShoelaceFormControl` interface to improve type safety and consistency
+- Updated Lit to 2.4.1
+- Updated `@shoelace-style/localize` t0 3.0.3 to support for extended language codes
+- Updated Bootstrap Icons to 1.10.2
+- Updated TypeScript to 4.8.4
+- Updated esbuild to 0.15.14
+- Updated all other dependencies to latest versions
+
+## 2.0.0-beta.83
+
+This release removes the `<sl-responsive-media>` component. When this component was introduced, support for [`aspect-ratio`](https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio)) wasn't great. These days, [the property is supported](https://caniuse.com/mdn-css_properties_aspect-ratio) by all of Shoelace's target browsers, making a dedicated component redundant.
+
+- 🚨 BREAKING: Removed `<sl-responsive-media>` (use the well-supported `aspect-ratio` CSS property instead)
+- 🚨 BREAKING: Changed the `toggle-password` attribute of `<sl-input>` to `password-toggle` for consistency
+- Added an expand/collapse animation to `<sl-tree-item>`
+- Added `sl-lazy-change` event to `<sl-tree-item>`
+- Added `expand-button` part to `<sl-tree-item>` [#893](https://github.com/shoelace-style/shoelace/pull/893)
+- Added `password-visible` attribute to `<sl-input>` [#913](https://github.com/shoelace-style/shoelace/issues/913)
+- Fixed a bug in `<sl-popup>` that didn't account for the arrow's diagonal size
+- Fixed a bug in `<sl-popup>` that caused arrow placement to be incorrect with RTL
+- Fixed a bug in `<sl-progress-ring>` that caused the indeterminate animation to stop working in Safari [#891](https://github.com/shoelace-style/shoelace/issues/891)
+- Fixed a bug in `<sl-range>` that caused it to overflow a container at 100% width [#905](https://github.com/shoelace-style/shoelace/issues/905)
+- Fixed a bug in `<sl-tree-item>` that prevented custom expand/collapse icons from rendering
+- Fixed a bug in `<sl-tree-item>` where the `expand-icon` and `collapse-icon` slots were reversed
+- Fixed a bug in `<sl-tree-item>` that prevented the keyboard from working after lazy loading [#882](https://github.com/shoelace-style/shoelace/issues/882)
+- Fixed a bug in `<sl-textarea>` that prevented the textarea from resizing automatically when setting the value programmatically [#912](https://github.com/shoelace-style/shoelace/discussions/912)
+- Fixed a handful of paths to prevent TypeScript from getting upset [#886](https://github.com/shoelace-style/shoelace/issues/886)
+- Fixed a bug in `<sl-radio-group>` where the `button-group__base` part was documented but not exposed [#909](https://github.com/shoelace-style/shoelace/discussions/909)
+- Fixed a bug in `<sl-range>` that caused the active track color to render on the wrong side in RTL [#916](https://github.com/shoelace-style/shoelace/issues/916)
+- Refactored the internal event emitter to be part of `ShoelaceElement` to reduce imports and improve DX
+- Downgraded Floating UI from 1.0.1 to 1.0.0 due to new logic that makes positioning much slower for certain components [#915](https://github.com/shoelace-style/shoelace/issues/915)
+- Upgraded the status of `<sl-animated-image>`, `<sl-popup>`, and `<sl-split-panel>` from experimental to stable
+
+## 2.0.0-beta.82
+
+- Added the `sync` and `arrow-placement` attributes to `<sl-popup>`
+- Changed the `auto-size` attribute of the experimental `<sl-popup>` component so it accepts `horizontal`, `vertical`, and `both` instead of a boolean value
+- Changed the `flip-fallback-placement` attribute of the experimental `<sl-popup>` component to `flip-fallback-placements`
+- Changed the `flip-fallback-strategy` in the experimental `<sl-popup>` component to accept `best-fit` and `initial` instead of `bestFit` and `initialPlacement`
+- Fixed a bug in `<sl-dropdown>` that caused the panel to resize horizontally when the trigger is clipped by the viewport [#860](https://github.com/shoelace-style/shoelace/issues/860)
+- Fixed a bug in `<sl-tree>` where dynamically changing slotted items wouldn't update the tree properly
+- Fixed a bug in `<sl-split-panel>` that caused the panel to stack when clicking on the divider in mobile versions of Chrome [#862](https://github.com/shoelace-style/shoelace/issues/862)
+- Fixed a bug in `<sl-popup>` that prevented flip fallbacks from working as intended
+- Fixed a bug that caused concurrent animations to work incorrectly when the durations were different [#867](https://github.com/shoelace-style/shoelace/issues/867)
+- Fixed a bug in `<sl-color-picker>` that caused the trigger and color preview to ignore opacity on first render [#869](https://github.com/shoelace-style/shoelace/issues/869)
+- Fixed a bug in `<sl-tree>` that prevented the keyboard from working when the component was nested in a shadow root [#871](https://github.com/shoelace-style/shoelace/issues/871)
+- Fixed a bug in `<sl-tab-group>` that prevented the keyboard from working when the component was nested in a shadow root [#872](https://github.com/shoelace-style/shoelace/issues/872)
+- Fixed a bug in `<sl-tab>` that allowed disabled tabs to erroneously receive focus
+- Improved single selection in `<sl-tree>` so nodes expand and collapse and rece
+  ive selection when clicking on the label
+- Renamed `expanded-icon` and `collapsed-icon` slots to `expand-icon` and `collapse-icon` in the experimental `<sl-tree>` and `<sl-tree-item>` components
+- Improved RTL support for `<sl-image-comparer>`
+- Refactored components to extend from `ShoelaceElement` to make `dir` and `lang` reactive properties in all components
+
+## 2.0.0-beta.81
+
+- 🚨 BREAKING: removed the `base` part from `<sl-menu>` and removed an unnecessary `<div>` that made styling more difficult
+- Added the `anchor` property to `<sl-popup>` to support external anchors
+- Added read-only custom properties `--auto-size-available-width` and `--auto-size-available-height` to `<sl-popup>` to improve support for overflowing popup content
+- Added `label` to `<sl-rating>` to improve accessibility for screen readers
+- Added the `base__popup` and `base__arrow` parts to `<sl-tooltip>` [#858](https://github.com/shoelace-style/shoelace/issues/858)
+- Fixed a bug where auto-size wasn't being applied to `<sl-dropdown>` and `<sl-select>`
+- Fixed a bug in `<sl-popup>` that caused auto-size to kick in before flip
+- Fixed a bug in `<sl-popup>` that prevented the `arrow-padding` attribute from working as expected
+- Fixed a bug in `<sl-tooltip>` that prevented the popup from appearing with the correct z-index [#854](https://github.com/shoelace-style/shoelace/issues/854)
+- Improved accessibility of `<sl-rating>` so keyboard nav works better and screen readers announce it properly
+- Improved accessibility of `<sl-spinner>` so screen readers no longer skip over it
+- Removed a user agent sniffing notice that appeared in Chrome [#855](https://github.com/shoelace-style/shoelace/issues/855)
+- Removed the default hover effect in `<sl-tree-items>` to make selections more obvious
+- Updated Floating UI to 1.0.1
+- Updated esbuild to 0.15.1
+- Updated all other dependencies to latest versions
+
+## 2.0.0-beta.80
+
+This release breaks radio buttons, which is something that needed to happen to solve a longstanding accessibility issue where screen readers announced an incorrect number of radios, e.g. "1 of 1" instead of "1 of 3." Many attempts to solve this without breaking the existing API were made, but none worked across the board. The new implementation upgrades `<sl-radio-group>` to serve as the "form control" while `<sl-radio>` and `<sl-radio-button>` serve as options within the form control.
+
+To upgrade to this version, you will need to rework your radio controls by moving `name` up to the radio group. And instead of setting `checked` to select a specific radio, you can set `value` on the radio group and the checked item will update automatically.
+
+- 🚨 BREAKING: improved accessibility of `<sl-radio-group>`, `<sl-radio>`, and `<sl-radio-button>` so they announce properly in screen readers
+  - Added the `name` attribute to `<sl-radio-group>` and removed it from `<sl-radio>` and `<sl-radio-button>`
+  - Added the `value` attribute to `<sl-radio-group>` (use this to control which radio is checked)
+  - Added the `sl-change` event to `sl-radio-group`
+  - Added `setCustomValidity()` and `reportValidity()` to `<sl-radio-group>`
+  - Removed the `checked` attribute from `<sl-radio>` and `<sl-radio-button>` (use the radio group's `value` attribute instead)
+  - Removed the `sl-change` event from `<sl-radio>` and `<sl-radio-button>` (listen for it on the radio group instead)
+  - Removed the `invalid` attribute from `<sl-radio>` and `<sl-radio-button>`
+  - Removed `setCustomValidity()` and `reportValidity()` from `<sl-radio>` and `<sl-radio-button>` (now available on the radio group)
+- Added the experimental `<sl-popup>` component
+- Fixed a bug in `<sl-menu-item>` where labels weren't always aligned correctly
+- Fixed a bug in `<sl-range>` that caused the tooltip to be positioned incorrectly when switching between LTR/RTL
+- Refactored `<sl-dropdown>` to use `<sl-popup>`
+- Refactored `<sl-tooltip>` to use `<sl-popup>` and added the `body` part
+- Revert disabled focus behavior in `<sl-tab-group>`, `<sl-menu>`, and `<sl-tree>` to be consistent with native form controls and menus [#845](https://github.com/shoelace-style/shoelace/issues/845)
+
+## 2.0.0-beta.79
+
+- Added experimental `<sl-tree>` and `<sl-tree-item>` components [#823](https://github.com/shoelace-style/shoelace/pull/823)
+- Added `--indicator-width` custom property to `<sl-progress-ring>` [#837](https://github.com/shoelace-style/shoelace/issues/837)
+- Added Swedish translation [#838](https://github.com/shoelace-style/shoelace/pull/838)
+- Added support for `step="any"` for `<sl-input type="number">` [#839](https://github.com/shoelace-style/shoelace/issues/839)
+- Changed the type of component styles from `CSSResult` to `CSSResultGroup` [#828](https://github.com/shoelace-style/shoelace/issues/828)
+- Fixed a bug in `<sl-color-picker>` where using <kbd>Left</kbd> and <kbd>Right</kbd> would select the wrong color
+- Fixed a bug in `<sl-dropdown>` that caused the position to be incorrect on the first show when using `hoist` [#843](https://github.com/shoelace-style/shoelace/issues/843)
+- Fixed a bug in `<sl-tab-group>` where the divider was on the wrong side when using `placement="end"`
+- Fixed a bug in `<sl-tab-group>` that caused nested tab groups to scroll when using `placement="start|end"` [#815](https://github.com/shoelace-style/shoelace/issues/815)
+- Fixed a bug in `<sl-tooltip>` that caused the target to be lost after a slot change [#831](https://github.com/shoelace-style/shoelace/pull/831)
+- Fixed a bug in `<sl-tooltip>` that caused the position to be incorrect on the first show when using `hoist`
+- Improved accessibility of `<sl-tab-group>`, `<sl-tab>`, and `<sl-tab-panel>` to announce better in screen readers and by allowing focus on disabled items
+- Improved accessibility of `<sl-menu>` and `<sl-menu-item>` by allowing focus on disabled items
+- Updated Lit to 2.2.8
+- Update esbuild to 0.14.50
+- Updated Bootstrap Icons to 1.9.1
+- Updated Floating UI to 1.0.0
+- Updated all other dependencies to latest versions
+
+## 2.0.0-beta.78
+
+- 🚨 BREAKING: Moved the `checked-icon` and `indeterminate-icon` parts from a wrapper `<span>` to the `<svg>` in `<sl-checkbox>` [#786](https://github.com/shoelace-style/shoelace/issues/786)
+- 🚨 BREAKING: Moved the `checked-icon` part from a wrapper `<span>` to the `<svg>` in `<sl-radio>` [#786](https://github.com/shoelace-style/shoelace/issues/786)
+- Added the `--track-active-offset` custom property to `<sl-range>` [#806](https://github.com/shoelace-style/shoelace/issues/806)
+- Fixed a bug that caused `<sl-select>` to sometimes have two vertical scrollbars [#814](https://github.com/shoelace-style/shoelace/issues/814)
+- Fixed a bug that caused a gray line to appear between radio buttons [#821](https://github.com/shoelace-style/shoelace/discussions/821)
+- Fixed a bug that caused `<sl-animated-image>` to not render anything when using the `play` attribute initially [#824](https://github.com/shoelace-style/shoelace/issues/824)
+- Removed `:focus-visible` shim now that the last two major versions of Safari support it
+- Updated Bootstrap Icons to 1.9.0
+- Updated esbuild to 0.14.49
+- Updated Floating UI to 0.5.4
+- Updated Lit to 2.2.7
+- Updated all other dependencies to latest versions
+
+## 2.0.0-beta.77
+
+- Added styles to required form controls so they show an asterisk next to the label by default
+- Added the `--sl-input-required-content` design token
+- Added the `required` attribute to `<sl-radio-group>` and fixed constraint validation logic to support custom validation
+- Added the `checked-icon` part to `<sl-menu-item>`
+- Added the `no-spin-buttons` attribute to `<sl-input type="number">` [#798](https://github.com/shoelace-style/shoelace/issues/798)
+- Added support for resetting forms using `<sl-button type="reset">` [#799](https://github.com/shoelace-style/shoelace/pull/799)
+- Fixed a bug where a duplicate clear button showed in Firefox [#791](https://github.com/shoelace-style/shoelace/issues/791)
+- Fixed a bug where setting `valueAsDate` or `valueAsNumber` too early on `<sl-input>` would throw an error [#796](https://github.com/shoelace-style/shoelace/issues/796)
+- Fixed a bug in `<sl-color-picker>` where empty values weren't properly supported [#797](https://github.com/shoelace-style/shoelace/issues/797)
+- Fixed a bug in `<sl-color-picker>` where values were logged to the console when using the keyboard
+- Fixed a bug in `<sl-input>` where password controls would try to autocorrect/autocomplete/autocapitalize when the password is visible
+- Fixed label alignment in `<sl-checkbox>` and `<sl-radio>` so they align to the top of the control instead of the center when wrapping
+- Fixed labels in `<sl-checkbox>` and `<sl-radio>` so they use the `--sl-input-label-color` design token
+- Improved performance of the tabbable utility which can prevent the browser from temporarily locking up in focus traps [#800](https://github.com/shoelace-style/shoelace/pull/800)
+- Updated the `fieldset` attribute so it reflects in `<sl-radio-group>`
+
+## 2.0.0-beta.76
+
+- Added support for RTL animations in the Animation Registry
+- Fixed a bug where the bottom border of `<sl-select>` could be cut off when the dropdown scrolls
+- Fixed a bug in `<sl-select>` that could result in the browser locking up due to an infinite positioning loop [#777](https://github.com/shoelace-style/shoelace/issues/777)
+- Improved RTL animations for `<sl-drawer>` [#784](https://github.com/shoelace-style/shoelace/issues/784)
+- Improved RTL styles for `<sl-button-group>` [#783](https://github.com/shoelace-style/shoelace/issues/783)
+- Improved RTL styles for the toast stack [#785](https://github.com/shoelace-style/shoelace/issues/785)
+- Improved typings for translations and localized terms
+- Upgraded @shoelace-style/localize to 3.0
+
+## 2.0.0-beta.75
+
+- Added Persian translation [#774](https://github.com/shoelace-style/shoelace/pull/774)
+- Added `color-scheme` to light and dark themes to improve rendering of browser-provided UI [#776](https://github.com/shoelace-style/shoelace/issues/776)
+- Added `--track-width` custom property to `<sl-tab-group>`
+- Fixed focus rings for `<sl-input>`, `<sl-select>`, and `<sl-textarea>` in Safari since they don't use `:focus-visible` [#767](https://github.com/shoelace-style/shoelace/issues/767)
+- Fixed a bug where calling `HTMLFormElement.reportValidity()` would skip Shoelace form controls [#772](https://github.com/shoelace-style/shoelace/issues/772)
+- Fixed a bug that prevented `<sl-tooltip>` from closing when disabled [#775](https://github.com/shoelace-style/shoelace/issues/775)
+- Fixed a bug that allowed `<sl-icon-button>` to emit a `click` event when disabled [#781](https://github.com/shoelace-style/shoelace/issues/781)
+- Improved the default icon for `<sl-image-comparer>` so it's more intuitive and removed `grip-vertical` from system icon library
+- Improved RTL styles for many components [#768](https://github.com/shoelace-style/shoelace/pull/768)
+- Improved base path logic to execute only when `getBasePath()` is first called to better support SSR [#778](https://github.com/shoelace-style/shoelace/issues/778)
+- Improved `DOMParser` instantiation in `<sl-icon>` to better support SSR [#778](https://github.com/shoelace-style/shoelace/issues/778)
+- Reverted menu item caching due to regression [#766](https://github.com/shoelace-style/shoelace/issues/766)
+- Updated Floating UI to 0.5.2
+
+## 2.0.0-beta.74
+
+- 🚨 BREAKING: reworked focus rings to use outlines instead of box shadows
+  - Removed the `--sl-focus-ring-alpha` design token
+  - Refactored `--sl-focus-ring` to be an `outline` property instead of a `box-shadow` property
+  - Added `--sl-focus-ring-color`, `--sl-focus-ring-style`, and `--sl-focus-ring-offset`
+- 🚨 BREAKING: removed `variant` from `<sl-radio-button>`
+- Added `sl-label-change` event to `<sl-menu-item>`
+- Added `blur()`, `click()`, and `focus()` methods as well as `sl-blur` and `sl-focus` events to `<sl-icon-button>` [#730](https://github.com/shoelace-style/shoelace/issues/730)
+- Added Tabler Icons example to icons page
+- Fixed a bug where updating a menu item's label wouldn't update the display label in `<sl-select>` [#729](https://github.com/shoelace-style/shoelace/issues/729)
+- Fixed a bug where the FormData event polyfill was causing issues with older browsers [#747](https://github.com/shoelace-style/shoelace/issues/747)
+- Fixed a bug that caused a console error when setting `value` to `null` or `undefined` in `<sl-input>`, `<sl-select>`, and `<sl-textarea>` [#751](https://github.com/shoelace-style/shoelace/pull/751)
+- Fixed a bug that caused `<sl-checkbox>` and `<sl-radio>` controls without a `value` to submit as `null` instead of `on` like native inputs [#744](https://github.com/shoelace-style/shoelace/issues/744)
+- Fixed a bug that caused `<sl-dropdown>` and dependent components to add unexpected padding around the panel [#743](https://github.com/shoelace-style/shoelace/issues/743)
+- Fixed a bug that prevented `valueAsDate` and `valueAsNumber` from updating synchronously [#760](https://github.com/shoelace-style/shoelace/issues/760)
+- Fixed a bug that caused `<sl-menu-item>` to load icons from the default library instead of the system library [#765](https://github.com/shoelace-style/shoelace/issues/765)
+- Fixed a bug in `<sl-input>` that prevented a canceled `keydown` event from submitting the containing form when pressing enter [#764](https://github.com/shoelace-style/shoelace/issues/764)
+- Improved behavior of clearable and password toggle buttons in `<sl-input>` and `<sl-select>` [#745](https://github.com/shoelace-style/shoelace/issues/745)
+- Improved performance of `<sl-select>` by caching menu items instead of traversing for them each time
+- Improved drag utility so initial click/touch events can be accepted [#758](https://github.com/shoelace-style/shoelace/issues/758)
+- Improved `<sl-color-picker>` to use an HSB grid instead of HSL to be more consistent with existing color picker implementations [#762](https://github.com/shoelace-style/shoelace/issues/762)
+- Improved `<sl-color-picker>` so the cursor is hidden and the preview is larger when dragging the grid
+- Refactored `<sl-menu>` to be more performant by caching menu items on slot change
+- Reverted form submit logic [#718](https://github.com/shoelace-style/shoelace/issues/718)
+- Updated the `disabled` attribute so it reflects in `<sl-dropdown>` [#741](https://github.com/shoelace-style/shoelace/discussions/741)
+- Updated the `name` and `icon` attribute so they reflect in `<sl-icon>` [#742](https://github.com/shoelace-style/shoelace/pull/742)
+- Updated Lit to 2.2.5
+- Updated Bootstrap Icons to 1.8.3
+- Updated TypeScript to 4.7.2
+- Updated esbuild to 0.14.40
+- Updated all other dependencies to latest versions
+
+## 2.0.0-beta.73
+
+- Added `button` part to `<sl-radio-button>`
+- Added custom validity examples and tests to `<sl-checkbox>`, `<sl-radio>`, and `<sl-radio-button>`
+- Added `enterkeyhint` attribute to `<sl-input>` and `<sl-textarea>`
+- Fixed a bug that prevented `setCustomValidity()` from working with `<sl-radio-button>`
+- Fixed a bug where the right border of a checked `<sl-radio-button>` was the wrong color
+- Fixed a bug that prevented a number of properties, methods, etc. from being documented in `<sl-radio>` and `<sl-radio-button>`
+- Fixed a bug in `<sl-avatar>` that prevented valid images from showing after an invalid or missing image was provided [#717](https://github.com/shoelace-style/shoelace/issues/717)
+- Fixed a bug that resulted in a console error being thrown on keydown in `<sl-dropdown>` [#719](https://github.com/shoelace-style/shoelace/issues/719)
+- Fixed a bug that prevented `<sl-dropdown>` from being closed when opened initially [#720](https://github.com/shoelace-style/shoelace/issues/720)
+- Fixed a bug that caused the test runner to fail when using a locale other than en-US [#726](https://github.com/shoelace-style/shoelace/issues/726)
+- Improved form submit logic so most user-added event listeners will run after form data is attached and validation occurs [#718](https://github.com/shoelace-style/shoelace/issues/718)
+- Improved accessibility of `<sl-tooltip>` so screen readers announce the content on hover/focus [#219](https://github.com/shoelace-style/shoelace/issues/219)
+- Improved accessibility of form controls by exposing clear buttons and password visibility buttons to screen readers while keeping them out of the tab order [#727](https://github.com/shoelace-style/shoelace/issues/727)
+- Updated `<sl-tab-group>` and `<sl-menu>` to cycle through tabs and menu items instead of stopping at the first/last when using the keyboard
+- Removed path aliasing (again) because it doesn't work with Web Test Runner's esbuild plugin
+
+## 2.0.0-beta.72
+
+- 🚨 BREAKING: refactored parts in `<sl-input>`, `<sl-range>`, `<sl-select>`, and `<sl-textarea>` to allow you to customize the label and help text position
+  - Added `form-control-input` part
+  - Renamed `label` to `form-control-label`
+  - Renamed `help-text` to `form-control-help-text`
+- 🚨 BREAKING: removed status from the `sl-error` event payload in `<sl-icon>`
+- Added the experimental `<sl-radio-button>` component
+- Added `button-group` and `button-group__base` parts to `<sl-radio-group>`
+- Added the `label` attribute and slot to `<sl-color-picker>` to improve accessibility with screen readers
+- Fixed a bug that prevented form submission from working as expected in some cases
+- Fixed a bug that prevented `<sl-split-panel>` from toggling `vertical` properly [#703](https://github.com/shoelace-style/shoelace/issues/703)
+- Fixed a bug that prevented `<sl-color-picker>` from rendering a color initially [#704](https://github.com/shoelace-style/shoelace/issues/704)
+- Fixed a bug that caused focus trapping to fail when used inside a shadow root [#709](https://github.com/shoelace-style/shoelace/issues/709)
+- Improved accessibility throughout the docs
+- Improved accessibility of `<sl-dropdown>` so the trigger's expanded state is announced correctly
+- Improved accessibility of `<sl-format-date>` but rendering a `<time>` element instead of plain text
+- Improved accessibility of `<sl-select>` so disabled controls announce correct
+- Improved accessibility in `<sl-tag>` so remove buttons have labels
+- Refactored `<sl-radio>` to move selection logic into `<sl-radio-group>`
+- Updated slot detection logic so it ignores visually hidden elements
+- Upgraded the status of `<sl-visually-hidden>` from experimental to stable
+
+## 2.0.0-beta.71
+
+- 🚨 BREAKING: refactored exported parts to ensure composed components and their parts can be targeted via CSS
+  - Refactored the `eye-dropper-button` part and added `eye-dropper-button__base`, `eye-dropper-button__prefix`, `eye-dropper-button__label`, `eye-dropper-button__suffix`, and `eye-dropper-button__caret` parts to `<sl-color-picker>`
+  - Refactored the `format-button` part and added `format-button__base`, `format-button__prefix`, `format-button__label`, `format-button__suffix`, and `format-button__caret` parts to `<sl-color-picker>`
+  - Moved the `close-button` part in `<sl-alert>` to the internal `<sl-icon-button>` and removed the `<span>` that wrapped it
+  - Moved the `close-button` part in `<sl-dialog>` and `<sl-drawer>` to point to the host element and added the `close-button__base` part
+  - Renamed parts in `<sl-select>` from `tag-base` to `tag__base`, `tag-content` to `tag__content`, and `tag-remove-button` to `tag__remove-button`
+  - Moved the `close-button` part in `<sl-tab>` to the internal `<sl-icon-button>` and added the `close-button__base` part
+  - Moved the `scroll-button` part in `<sl-tab-group>` to the internal `<sl-icon-button>` and added the `scroll-button__base`, `scroll-button--start`, and `scroll-button--end` parts
+  - Moved the `remove-button` part in `<sl-tag>` to the internal `<sl-icon-button>` and added the `remove-button__base` part
+- 🚨 BREAKING: removed `checked-icon` part from `<sl-menu-item>` in preparation for parts refactor
+- 🚨 BREAKING: changed the `typeToSelect()` method's argument from `String` to `KeyboardEvent` in `<sl-menu>` to support more advanced key combinations
+- Added `form`, `formaction`, `formmethod`, `formnovalidate`, and `formtarget` attributes to `<sl-button>` [#699](https://github.com/shoelace-style/shoelace/issues/699)
+- Added Prettier and ESLint to markdown files
+- Added background color and border to `<sl-menu>`
+- Added more tests for `<sl-input>`, `<sl-select>`, and `<sl-textarea>`
+- Fixed a bug that prevented forms from submitting when pressing <kbd>Enter</kbd> inside of an `<sl-input>` [#700](https://github.com/shoelace-style/shoelace/issues/700)
+- Fixed a bug in `<sl-input>` that prevented the `valueAsDate` and `valueAsNumber` properties from working when set before the component was initialized
+- Fixed a bug in `<sl-dropdown>` where pressing <kbd>Home</kbd> or <kbd>End</kbd> wouldn't select the first or last menu items, respectively
+- Improved `autofocus` behavior in Safari for `<sl-dialog>` and `<sl-drawer>` [#693](https://github.com/shoelace-style/shoelace/issues/693)
+- Improved type to select logic in `<sl-menu>` so it supports <kbd>Backspace</kbd> and gives users more time before resetting
+- Improved checkmark size and positioning in `<sl-menu-item>`
+- Improved accessibility in form controls that have help text so they're announced correctly in various screen readers
+- Removed feature detection for `focus({ preventScroll })` since it no longer works in Safari
+- Removed the `--sl-tooltip-arrow-start-end-offset` design token
+- Removed the `pattern` attribute from `<sl-textarea>` as it was documented incorrectly and never supported
+- Replaced Popper positioning dependency with Floating UI in `<sl-dropdown>` and `<sl-tooltip>`
+
+## 2.0.0-beta.70
+
+- Added `tag-base`, `tag-content`, and `tag-remove-button` parts to `<sl-select>` [#682](https://github.com/shoelace-style/shoelace/discussions/682)
+- Added support for focusing elements with `autofocus` when `<sl-dialog>` and `<sl-drawer>` open [#688](https://github.com/shoelace-style/shoelace/issues/688)
+- Added the `placement` attribute to `<sl-select>` [#687](https://github.com/shoelace-style/shoelace/pull/687)
+- Added Danish translation [#690](https://github.com/shoelace-style/shoelace/pull/690)
+- Fixed a bug that allowed `<sl-dropdown>` to go into an incorrect state when activating the trigger while disabled [#684](https://github.com/shoelace-style/shoelace/pull/684)
+- Fixed a bug where Safari would sometimes not focus after preventing `sl-initial-focus` [#688](https://github.com/shoelace-style/shoelace/issues/688)
+- Fixed a bug where the active tab indicator in `<sl-tab-group>` would be misaligned when using disabled tabs [#695](https://github.com/shoelace-style/shoelace/pull/695)
+- Improved the size of the remove button in `<sl-tag>`
+- Removed Google Analytics from the docs
+
+## 2.0.0-beta.69
+
+- Added `web-types.json` to improve the dev experience for WebStorm/PHPStorm users [#328](https://github.com/shoelace-style/shoelace/issues/328)
+- Fixed a bug that caused an error when pressing up/down in `<sl-select>`
+- Fixed a bug that caused `<sl-details>` to not show when double clicking the summary while open [#662](https://github.com/shoelace-style/shoelace/issues/662)
+- Fixed a bug that prevented the first/last menu item from receiving focus when pressing up/down in `<sl-dropdown>`
+- Fixed a bug that caused the active tab indicator in `<sl-tab-group>` to render incorrectly when used inside an element that animates [#671](https://github.com/shoelace-style/shoelace/pull/671)
+- Fixed a bug that allowed values in `<sl-range>` to be invalid according to its `min|max|step` [#674](https://github.com/shoelace-style/shoelace/issues/674)
+- Updated Lit to 2.1.4
+- Updated all other dependencies to latest versions
+
+## 2.0.0-beta.68
+
+- Fixed path aliases in generated files so they're relative again [#669](https://github.com/shoelace-style/shoelace/pull/669)
+
+## 2.0.0-beta.67
+
+- Fixed a TypeScript config regression introduced in [#647](https://github.com/shoelace-style/shoelace/pull/647) that removed the `rootDir`, breaking the expected build output
+
+## 2.0.0-beta.66
+
+- Attempted to fix a bug that prevented types from being generated in the build
+
+## 2.0.0-beta.65
+
+- 🚨 BREAKING: the `unit` property of `<sl-format-bytes>` has changed to `byte | bit` instead of `bytes | bits`
+- Added `display-label` part to `<sl-select>` [#650](https://github.com/shoelace-style/shoelace/issues/650)
+- Added `--spacing` custom property to `<sl-divider>` [#664](https://github.com/shoelace-style/shoelace/pull/664)
+- Added `event.detail.source` to the `sl-request-close` event in `<sl-dialog>` and `<sl-drawer>`
+- Fixed a bug that caused `<sl-progress-ring>` to render the wrong size when `--track-width` was increased [#656](https://github.com/shoelace-style/shoelace/issues/656)
+- Fixed a bug that allowed `<sl-details>` to open and close when disabled using a screen reader [#658](https://github.com/shoelace-style/shoelace/issues/658)
+- Fixed a bug in the FormData event polyfill that threw an error in some environments [#666](https://github.com/shoelace-style/shoelace/issues/666)
+- Implemented stricter linting to improve consistency and reduce errors, which resulted in many small refactors throughout the codebase [#647](https://github.com/shoelace-style/shoelace/pull/647)
+- Improved accessibility of `<sl-dialog>` and `<sl-drawer>` by making the title an `<h2>` and adding a label to the close button
+- Improved search results in the documentation
+- Refactored `<sl-format-byte>` to use `Intl.NumberFormat` so it supports localization
+- Refactored themes so utility styles are no longer injected as `<style>` elements to support stricter CSP rules [#571](https://github.com/shoelace-style/shoelace/issues/571)
+- Restored the nicer animation on `<sl-spinner>` and verified it works in Safari
+- Updated Feather icon example to use Lucide [#657](https://github.com/shoelace-style/shoelace/issues/657)
+- Updated minimum Node version to 14.17
+- Updated Lit to 2.1.2
+- Updated to Bootstrap Icons to 1.8.1
+- Updated all other dependencies to latest versions
+
+## 2.0.0-beta.64
+
+- 🚨 BREAKING: removed `<sl-form>` because all form components submit with `<form>` now ([learn more](/getting-started/form-controls))
+- 🚨 BREAKING: changed `submit` attribute to `type="submit"` on `<sl-button>`
+- 🚨 BREAKING: changed the `alt` attribute to `label` in `<sl-avatar>` for consistency with other components
+- Added `role="status"` to `<sl-spinner>`
+- Added `valueAsDate` and `valueAsNumber` properties to `<sl-input>` [#570](https://github.com/shoelace-style/shoelace/issues/570)
+- Added `start`, `end`, and `panel` parts to `<sl-split-panel>` [#639](https://github.com/shoelace-style/shoelace/issues/639)
+- Fixed broken spinner animation in Safari [#633](https://github.com/shoelace-style/shoelace/issues/633)
+- Fixed an a11y bug in `<sl-tooltip>` where `aria-describedby` referenced an id in the shadow root
+- Fixed a bug in `<sl-radio>` where tabbing didn't work properly in Firefox [#596](https://github.com/shoelace-style/shoelace/issues/596)
+- Fixed a bug in `<sl-input>` where clicking the left/right edge of the control wouldn't focus it
+- Fixed a bug in `<sl-input>` where autofill had strange styles [#644](https://github.com/shoelace-style/shoelace/pull/644)
+- Improved `<sl-spinner>` track color when used on various backgrounds
+- Improved a11y in `<sl-radio>` so VoiceOver announces radios properly in a radio group
+- Improved the API for the experimental `<sl-split-panel>` component by making `position` accept a percentage and adding the `position-in-pixels` attribute
+- Refactored `<sl-breadcrumb-item>`, `<sl-button>`, `<sl-card>`, `<sl-dialog>`, `<sl-drawer>`, `<sl-input>`, `<sl-range>`, `<sl-select>`, and `<sl-textarea>` to use a Reactive Controller for slot detection
+- Refactored internal id usage in `<sl-details>`, `<sl-dialog>`, `<sl-drawer>`, and `<sl-dropdown>`
+- Removed `position: relative` from the common component stylesheet
+- Updated Lit to 2.1.0
+- Updated all other dependencies to latest versions
+
+## 2.0.0-beta.63
+
+- 🚨 BREAKING: changed the `type` attribute to `variant` in `<sl-alert>`, `<sl-badge>`, `<sl-button>`, and `<sl-tag>` since it's more appropriate and to disambiguate from other `type` attributes
+- 🚨 BREAKING: removed `base` part from `<sl-divider>` to simplify the styling API
+- Added the experimental `<sl-split-panel>` component
+- Added `focus()` and `blur()` methods to `<sl-select>` [#625](https://github.com/shoelace-style/shoelace/pull/625)
+- Fixed a bug where setting `tooltipFormatter` on `<sl-range>` in JSX causes React@experimental to error out
+- Fixed a bug where clicking on a slotted icon in `<sl-button>` wouldn't submit forms [#626](https://github.com/shoelace-style/shoelace/issues/626)
+- Added the `sl-` prefix to generated ids for `<sl-tab>` and `<sl-tab-panel>`
+- Refactored `<sl-button>` to use Lit's static expressions to reduce code
+- Simplified `<sl-spinner>` animation
 
 ## 2.0.0-beta.62
 
@@ -28,9 +593,9 @@ This release improves the dark theme by shifting luminance in both directions, s
 
 In [beta.48](#_200-beta48), I introduced a change to color tokens that allowed you to access alpha values at the expense of a verbose, non-standard syntax. After considering feedback from the community, I've decided to revert this change so the `rgb()` function is no longer required. Many users reported never using it for alpha, and even more reported having trouble remembering to use `rgb()` and that it was causing more harm than good.
 
-Furthermore, both Safari and Firefox have implemented [`color-mix()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color-mix()) behind a flag, so access to alpha channels and other capabilities are coming to the browser soon.
+Furthermore, both Safari and Firefox have implemented [`color-mix()`](<https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color-mix()>) behind a flag, so access to alpha channels and other capabilities are coming to the browser soon.
 
-If you're using color tokens in your own stylesheet, simply remove the `rgb()` to update to this version. 
+If you're using color tokens in your own stylesheet, simply remove the `rgb()` to update to this version.
 
 ```css
 .your-styles {
@@ -55,7 +620,7 @@ Thank you for your help and patience with testing Shoelace. I promise, we're not
 - Improved a11y of the scroll buttons in `<sl-tab-group>`
 - Improved a11y of the close button in `<sl-tab>`
 - Improved a11y of `<sl-tab-panel>` by removing an invalid `aria-selected` attribute [#579](https://github.com/shoelace-style/shoelace/issues/579)
-- Improved a11y of `<sl-icon>` by not using a variation of the `name` attribute for labels (use the `label` prop instead)
+- Improved a11y of `<sl-icon>` by not using a variation of the `name` attribute for labels (use the `label` attribute instead)
 - Moved `role` from the shadow root to the host element in `<sl-menu>`
 - Removed redundant `role="menu"` in `<sl-dropdown>`
 - Slightly faster animations for showing and hiding `<sl-dropdown>`
@@ -117,7 +682,7 @@ This release is the second attempt at unbundling dependencies. This will be a br
 Shoelace doesn't have a lot of dependencies, but this release unbundles most of them so you can potentially save some extra kilobytes. This will be a breaking change only if your configuration _does not_ support bare module specifiers. CDN users and bundler users will be unaffected.
 
 - 🚨 BREAKING: renamed the `sl-clear` event to `sl-remove`, the `clear-button` part to `remove-button`, and the `clearable` property to `removable` in `<sl-tag>`
-- Added the `disabled` prop to `<sl-resize-observer>`
+- Added the `disabled` attribute to `<sl-resize-observer>`
 - Fixed a bug in `<sl-mutation-observer>` where setting `disabled` initially didn't work
 - Unbundled dependencies and configured external imports to be packaged with bare module specifiers
 
@@ -204,9 +769,9 @@ This release also fixes a critical bug in the color scale where `--sl-color-neut
 
 ## 2.0.0-beta.48
 
-This release improves theming by offering both light and dark themes that can be used autonomously. It also improves contrast in most components, adds a variety of new color primitives, and changes the way color tokens are consumed. 
+This release improves theming by offering both light and dark themes that can be used autonomously. It also improves contrast in most components, adds a variety of new color primitives, and changes the way color tokens are consumed.
 
-Previously, color tokens were in hexidecimal format. Now, Shoelace now uses an `R G B` format that requires you to use the `rgb()` function in your CSS.
+Previously, color tokens were in hexadecimal format. Now, Shoelace now uses an `R G B` format that requires you to use the `rgb()` function in your CSS.
 
 ```css
 .example {
@@ -261,7 +826,7 @@ This release improves how component dependencies are imported. If you've been ch
 - Fixed a bug where tabbing into `<sl-radio-group>` would not always focus the checked radio
 - Fixed a bug in component styles that prevented the box sizing reset from being applied
 - Fixed a regression in `<sl-color-picker>` where dragging the grid handle wasn't smooth
-- Fixed a bug where slot detection could incorrecly match against slots of child elements [#481](https://github.com/shoelace-style/shoelace/pull/481)
+- Fixed a bug where slot detection could incorrectly match against slots of child elements [#481](https://github.com/shoelace-style/shoelace/pull/481)
 - Fixed a bug in `<sl-input>` where focus would move to the end of the input when typing in Safari [#480](https://github.com/shoelace-style/shoelace/issues/480)
 - Improved base path utility logic
 
@@ -298,7 +863,7 @@ The docs have been updated to use the new `custom-elements.json` file. If you're
 - Added `sl-request-close` event to `<sl-dialog>` and `<sl-drawer>`
 - Added `dialog.denyClose` and `drawer.denyClose` animations
 - Fixed a bug in `<sl-color-picker>` where setting `value` immediately wouldn't trigger an update
-- Fixed a bug in `<sl-dialog>` and `<sl-drawer>` where setting `open` intially didn't set a focus trap
+- Fixed a bug in `<sl-dialog>` and `<sl-drawer>` where setting `open` initially didn't set a focus trap
 - Fixed a bug that resulted in form controls having incorrect validity when `disabled` was initially set [#473](https://github.com/shoelace-style/shoelace/issues/473)
 - Fixed a bug in the docs that caused the metadata file to be requested twice
 - Fixed a bug where tabbing out of a modal would cause the browser to lag [#466](https://github.com/shoelace-style/shoelace/issues/466)
@@ -322,7 +887,7 @@ The docs have been updated to use the new `custom-elements.json` file. If you're
 
 - Added `?` to optional arguments in methods tables in the docs
 - Added the `scrollPosition()` method to `<sl-textarea>` to get/set scroll position
-- Added intial tests for `<sl-dialog>`, `<sl-drawer>`, `<sl-dropdown>`, and `<sl-tooltip>`
+- Added initial tests for `<sl-dialog>`, `<sl-drawer>`, `<sl-dropdown>`, and `<sl-tooltip>`
 - Fixed a bug in `<sl-tab-group>` where scrollable tab icons were not displaying correctly
 - Fixed a bug in `<sl-dialog>` and `<sl-drawer>` where preventing clicks on the overlay no longer worked as described [#452](https://github.com/shoelace-style/shoelace/issues/452)
 - Fixed a bug in `<sl-dialog>` and `<sl-drawer>` where setting initial focus no longer worked as described [#453](https://github.com/shoelace-style/shoelace/issues/453)
@@ -341,7 +906,7 @@ Technical reasons aside, canceling these events seldom led to a good user experi
 - 🚨 BREAKING: `sl-show` and `sl-hide` events are no longer cancelable
 - Added Iconoir example to the icon docs
 - Added Web Test Runner
-- Added intial tests for `<sl-alert>` and `<sl-details>`
+- Added initial tests for `<sl-alert>` and `<sl-details>`
 - Changed the `cancelable` default to `false` for the internal `@event` decorator
 - Fixed a bug where toggling `open` stopped working in `<sl-alert>`, `<sl-dialog>`, `<sl-drawer>`, `<sl-dropdown>`, and `<sl-tooltip>`
 - Fixed a bug in `<sl-range>` where setting a value outside the default `min` or `max` would clamp the value [#448](https://github.com/shoelace-style/shoelace/issues/448)
@@ -552,7 +1117,7 @@ The component API remains the same except for the changes noted below. Thanks fo
 - 🚨 BREAKING: Fixed animations bloat
   - Removed ~400 baked-in Animista animations because they were causing ~200KB of bloat (they can still be used with custom keyframes)
   - Reworked animations into a separate module ([`@shoelace-style/animations`](https://github.com/shoelace-style/animations)) so it's more maintainable and animations are sync with the latest version of animate.css
-  - Animation and easing names are now camelcase (e.g. `easeInOut` instead of `ease-in-out`)
+  - Animation and easing names are now camelCase (e.g. `easeInOut` instead of `ease-in-out`)
 - Added initial E2E tests [#169](https://github.com/shoelace-style/shoelace/pull/169)
 - Added the `FocusOptions` argument to all components that have a `setFocus()` method
 - Added `sl-initial-focus` event to `<sl-dialog>` and `<sl-drawer>` so focus can be customized to a specific element
@@ -623,7 +1188,7 @@ The component API remains the same except for the changes noted below. Thanks fo
 - Fixed a bug where `<sl-menu-item>` wouldn't render properly in the dark theme
 - Fixed a bug where `<sl-select>` would show an autocomplete menu
 - Improved placeholder contrast in dark theme
-- Updated to Boostrap Icons 1.1.0
+- Updated to Bootstrap Icons 1.1.0
 - Updated to Stencil 2.3.0
 
 ## 2.0.0-beta.22
@@ -661,7 +1226,7 @@ The component API remains the same except for the changes noted below. Thanks fo
 - Refactored `<sl-icon>` request logic and removed unused cache map
 - Reworked show/hide logic in `<sl-alert>`, `<sl-dialog>`, and `<sl-drawer>` to not use reflow hacks and the `hidden` attribute
 - Reworked slot logic in `<sl-card>`, `<sl-dialog>`, and `<sl-drawer>`
-- Updated to Popper 2.5.3 to address a fixed position bug in Firefox 
+- Updated to Popper 2.5.3 to address a fixed position bug in Firefox
 
 ## 2.0.0-beta.20
 

docs/resources/community.md

@@ -13,7 +13,7 @@ The [discussion forum](https://github.com/shoelace-style/shoelace/discussions) i
 - Show the community what you're working on
 - Learn more about the project, its values, and its roadmap
 
-<sl-button type="primary" href="https://github.com/shoelace-style/shoelace/discussions" target="_blank">
+<sl-button variant="primary" href="https://github.com/shoelace-style/shoelace/discussions" target="_blank">
   <sl-icon name="github" slot="prefix"></sl-icon>
   Join the Discussion
 </sl-button>
@@ -27,7 +27,7 @@ The [community chat](https://discord.gg/mg8f26C) is open to the public and power
 - Show the community what you're working on
 - Chat live with other designers, developers, and Shoelace fans
 
-<sl-button type="primary" href="https://discord.gg/mg8f26C" target="_blank">
+<sl-button variant="primary" href="https://discord.gg/mg8f26C" target="_blank">
   <sl-icon name="discord" slot="prefix"></sl-icon>
   Join the Chat
 </sl-button>
@@ -36,7 +36,7 @@ The [community chat](https://discord.gg/mg8f26C) is open to the public and power
 
 You can post questions on Stack Overflow using [the "shoelace" tag](https://stackoverflow.com/questions/tagged/shoelace). This is a public forum where talented developers answer questions. It's a great way to get help, but it is not maintained by the Shoelace author.
 
-<sl-button type="primary" href="https://stackoverflow.com/questions/ask?tags=shoelace" target="_blank">
+<sl-button variant="primary" href="https://stackoverflow.com/questions/ask?tags=shoelace" target="_blank">
   <sl-icon name="stack-overflow" slot="prefix"></sl-icon>
   Ask for Help
 </sl-button>
@@ -47,7 +47,7 @@ Follow [@shoelace_style](https://twitter.com/shoelace_style) on Twitter for gene
 
 **Please avoid using Twitter for support questions.** The [discussion forum](https://github.com/shoelace-style/shoelace/discussions) is a much better place to share code snippets, screenshots, and other troubleshooting info. You'll have much better luck there, as more users will have a chance to help you.
 
-<sl-button type="primary" href="https://twitter.com/shoelace_style" target="_blank">
+<sl-button variant="primary" href="https://twitter.com/shoelace_style" target="_blank">
   <sl-icon name="twitter" slot="prefix"></sl-icon>
   Follow on Twitter
 </sl-button>