2.0.0-beta.66

* Adding Gitpod setup

* remove specifying vscode extensions in gitpod

* Allow ports 4000-4999

* Make local dev env instructions the first option

.eslintignore

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

.eslintrc.cjs

@@ -0,0 +1,256 @@
+/* eslint-env node */
+
+module.exports = {
+  plugins: ['@typescript-eslint', 'wc', 'lit', 'lit-a11y', 'chai-expect', 'chai-friendly', 'import'],
+  extends: [
+    'eslint:recommended',
+    'plugin:wc/recommended',
+    'plugin:wc/best-practice',
+    'plugin:lit/recommended',
+    'plugin:lit-a11y/recommended'
+  ],
+  env: {
+    es2021: true,
+    browser: true
+  },
+  reportUnusedDisableDirectives: 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',
+        // These are commented out for now as we may want to add them to improve function boundary safety
+        // "@typescript-eslint/explicit-function-return-type": [
+        //     "error",
+        //     {
+        //         allowTypedFunctionExpressions: true,
+        //     },
+        // ],
+        // "@typescript-eslint/explicit-member-accessibility": "warn",
+        // "@typescript-eslint/explicit-module-boundary-types": "error",
+        '@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': 'warn',
+        '@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-readonly': '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/naming-convention': [
+          'warn',
+          {
+            selector: 'default',
+            format: ['camelCase']
+          },
+          {
+            selector: ['function', 'enumMember', 'property'],
+            format: ['camelCase', 'PascalCase']
+          },
+          {
+            selector: 'variable',
+            modifiers: ['const'],
+            format: ['camelCase', 'PascalCase', 'UPPER_CASE']
+          },
+          {
+            selector: 'typeLike',
+            format: ['PascalCase']
+          },
+          {
+            selector: 'typeProperty',
+            format: ['camelCase', 'PascalCase', 'UPPER_CASE']
+          },
+          {
+            selector: 'objectLiteralProperty',
+            format: null
+          }
+        ],
+        '@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-unused-expressions': 'off'
+      }
+    }
+  ],
+  rules: {
+    'no-template-curly-in-string': 'error',
+    'array-callback-return': 'error',
+    'consistent-return': 'error',
+    curly: 'off',
+    'default-param-last': 'error',
+    eqeqeq: 'error',
+    '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: 'error',
+    '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': 'warn',
+    'no-else-return': 'warn',
+    'func-names': ['warn', 'never'],
+    'func-style': ['warn', 'declaration'],
+    'one-var': ['warn', 'never'],
+    'operator-assignment': 'warn',
+    'prefer-arrow-callback': 'warn',
+    'no-restricted-syntax': [
+      'warn',
+      {
+        selector: "CallExpression[callee.name='String']",
+        message: "Don't use the String function. Use .toString() instead."
+      },
+      {
+        selector: "CallExpression[callee.name='Number']",
+        message: "Don't use the Number function. Use parseInt or parseFloat instead."
+      },
+      {
+        selector: "CallExpression[callee.name='Boolean']",
+        message: "Don't use the Boolean function. Use a strict comparison instead."
+      }
+    ],
+    'no-restricted-imports': [
+      'warn',
+      {
+        patterns: [
+          {
+            group: ['../*'],
+            message: 'Usage of relative parent imports is not allowed.'
+          }
+        ],
+        paths: [
+          {
+            name: '.',
+            message: 'Usage of local index imports is not allowed.'
+          },
+          {
+            name: './index',
+            message: 'Import from the source file instead.'
+          }
+        ]
+      }
+    ],
+    'import/no-duplicates': 'warn',
+    'import/order': [
+      'warn',
+      {
+        groups: ['builtin', 'external', ['parent', 'sibling', 'internal', 'index']],
+        pathGroups: [
+          {
+            pattern: '~/**',
+            group: 'internal'
+          },
+          {
+            pattern: 'dist/**',
+            group: 'external'
+          }
+        ],
+        alphabetize: {
+          order: 'asc',
+          caseInsensitive: true
+        },
+        'newlines-between': 'never',
+        warnOnUnassignedImports: true
+      }
+    ],
+    'wc/guard-super-call': 'off'
+  }
+};

.github/workflows/node.js.yml

@@ -5,13 +5,12 @@ name: Node.js CI
 
 on:
   push:
-    branches: [ next ]
+    branches: [next]
   pull_request:
-    branches: [ next ]
+    branches: [next]
 
 jobs:
   build:
-
     runs-on: ubuntu-latest
 
     strategy:
@@ -20,12 +19,12 @@ jobs:
         # 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: npm ci
-    - run: npm run build --if-present
-    - run: npm test
+      - 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 verify

.gitignore

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

.gitpod.yml

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

.husky/pre-commit

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

.prettierignore

@@ -2,9 +2,12 @@
 *.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"
   ]
 }

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,126 @@
+{
+  "version": "0.2",
+  "words": [
+    "allowfullscreen",
+    "animationend",
+    "Animista",
+    "apos",
+    "atrule",
+    "autocorrect",
+    "autoplay",
+    "bezier",
+    "boxicons",
+    "chatbubble",
+    "claviska",
+    "Clippy",
+    "codepen",
+    "colocated",
+    "combobox",
+    "Composability",
+    "Consolas",
+    "contenteditable",
+    "copydir",
+    "coverpage",
+    "crossorigin",
+    "crutchcorn",
+    "csspart",
+    "cssproperty",
+    "datetime",
+    "describedby",
+    "Docsify",
+    "dropdowns",
+    "easings",
+    "erroneou",
+    "esbuild",
+    "exportparts",
+    "fieldsets",
+    "formdata",
+    "FOUC",
+    "FOUCE",
+    "fullscreen",
+    "giga",
+    "globby",
+    "Grayscale",
+    "haspopup",
+    "heroicons",
+    "hexa",
+    "Iconoir",
+    "Iframes",
+    "inputmode",
+    "ionicon",
+    "ionicons",
+    "jsDelivr",
+    "jsfiddle",
+    "keydown",
+    "keyframes",
+    "labelledby",
+    "Laravel",
+    "LaViska",
+    "litelement",
+    "lowercasing",
+    "Lucide",
+    "maxlength",
+    "Menlo",
+    "minlength",
+    "monospace",
+    "mousedown",
+    "mouseup",
+    "nextjs",
+    "noopener",
+    "noreferrer",
+    "novalidate",
+    "outdir",
+    "ParamagicDev",
+    "peta",
+    "petabit",
+    "popperjs",
+    "progressbar",
+    "radiogroup",
+    "Railsbyte",
+    "remixicon",
+    "reregister",
+    "resizer",
+    "resizers",
+    "rgba",
+    "roadmap",
+    "Roboto",
+    "saturationl",
+    "Schilp",
+    "Segoe",
+    "semibold",
+    "slotchange",
+    "spacebar",
+    "stylesheet",
+    "Tabbable",
+    "tabindex",
+    "tablist",
+    "tabpanel",
+    "templating",
+    "tera",
+    "textareas",
+    "transitionend",
+    "Triaging",
+    "turbolinks",
+    "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,18 +1,20 @@
 import fs from 'fs';
-import commentParser from 'comment-parser';
+import { parse } from 'comment-parser';
+import { pascalCase } from 'pascal-case';
 
 const packageData = JSON.parse(fs.readFileSync('./package.json', 'utf8'));
 const { name, description, version, author, homepage, license } = packageData;
+// eslint-disable-next-line func-style
 const noDash = string => string.replace(/^\s?-/, '').trim();
 
 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 };
       }
     },
@@ -20,9 +22,9 @@ 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'];
@@ -38,8 +40,8 @@ export default {
               });
             });
 
-            const parsed = commentParser.parse(customComments + '\n */');
-            parsed[0].tags?.map(t => {
+            const parsed = parse(`${customComments}\n */`);
+            parsed[0].tags?.forEach(t => {
               switch (t.tag) {
                 // Animations
                 case 'animation':
@@ -79,6 +81,25 @@ export default {
                   });
               }
             });
+          }
+        }
+      }
+    },
+
+    {
+      name: 'shoelace-react-event-names',
+      analyzePhase({ ts, node, moduleDoc }) {
+        switch (node.kind) {
+          case ts.SyntaxKind.ClassDeclaration: {
+            const className = node.name.getText();
+            const classDoc = moduleDoc?.declarations?.find(declaration => declaration.name === className);
+
+            if (classDoc?.events) {
+              classDoc.events.forEach(event => {
+                event.reactName = `on${pascalCase(event.name)}`;
+              });
+            }
+          }
         }
       }
     }

docs/_sidebar.md

@@ -4,9 +4,17 @@
   - [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)
 
@@ -21,13 +29,11 @@
   - [Card](/components/card)
   - [Checkbox](/components/checkbox)
   - [Color Picker](/components/color-picker)
-  - [Context Menu](/components/context-menu)
   - [Details](/components/details)
   - [Dialog](/components/dialog)
   - [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)
@@ -45,6 +51,7 @@
   - [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)
@@ -65,6 +72,7 @@
   - [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)

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

@@ -53,7 +53,7 @@
             <path d="M29.40483,205.96134 C25.92735,190.38755 37.0435,174.65088 54.23344,170.8125 C71.42338,166.97412 88.17766,176.48758 91.65513,192.06138 C95.1326,207.63518 83.74022,213.37903 66.55028,217.21738 C49.36034,221.05573 32.88231,221.53519 29.40483,205.96134 Z" id="Path" fill="#0ea5e9" fill-rule="nonzero"></path>
             <ellipse id="Oval" fill="#2F2E41" fill-rule="nonzero" transform="translate(22.673401, 226.029366) rotate(-64.625740) translate(-22.673401, -226.029366) " cx="22.6734006" cy="226.029366" rx="6.76007" ry="21.53368"></ellipse>
             <path d="M50.02702,261.54972 C50.02702,265.76487 60.88029,274.08829 72.92357,274.08829 C84.96685,274.08829 96.25871,262.22129 96.25871,258.0062 C96.25871,253.79111 84.96678,258.82395 72.92357,258.82395 C60.88036,258.82395 50.02702,257.33457 50.02702,261.54972 Z" id="Path" fill="#FFFFFF" fill-rule="nonzero"></path>
-            <path d="M113.52376,81.56869 C111.867655,81.5704977 110.525568,82.9125851 110.52376,84.56869 L110.52376,208.56869 C110.525568,210.224795 111.867655,211.566882 113.52376,211.56869 L400.52376,211.56869 C402.179865,211.566882 403.521952,210.224795 403.52376,208.56869 L403.52376,84.56869 C403.521952,82.9125851 402.179865,81.5704977 400.52376,81.56869 L113.52376,81.56869 Z" id="Path" fill="#0ea5e9" fill-rule="nonzero"></path>
+            <path d="M113.52376,81.56869 C111.867655,81.5704977 110.525568,82.9125851 110.52376,84.56869 L110.52376,208.56869 C110.525568,210.224795 111.867655,211.566882 113.52376,211.56869 L400.52376,211.56869 C402.179865,211.566882 403.521952,210.224795 403.52376,208.56869 L403.52376,84.56869 C403.521952,82.9125851 402.179865,81.5704977 400.52376,81.56869 L113.52376,81.56869 Z" id="Path" fill="#fbc024" fill-rule="nonzero"></path>
             <circle id="Oval" fill="#FFFFFF" fill-rule="nonzero" cx="191.01816" cy="146.56869" r="29.1211"></circle>
             <path d="M256.7436,142.69417 C254.884983,142.724723 253.39428,144.240132 253.39428,146.099 C253.39428,147.957868 254.884983,149.473277 256.7436,149.50383 L348.68926,149.50383 C349.906316,149.524778 351.042001,148.894505 351.668119,147.850647 C352.294237,146.806789 352.31556,145.508108 351.72405,144.444258 C351.132539,143.380407 350.018157,142.713189 348.80107,142.69417 C348.763797,142.693537 348.726527,142.693537 348.68926,142.69417 L256.7436,142.69417 Z" id="b71acdfd-6a55-428e-917a-53f192cb0203" fill="#FFFFFF" fill-rule="nonzero"></path>
             <path d="M256.7436,122.96697 C254.884983,122.997523 253.39428,124.512932 253.39428,126.3718 C253.39428,128.230668 254.884983,129.746077 256.7436,129.77663 L302.65917,129.77663 C303.876249,129.797613 305.011971,129.167347 305.638111,128.123473 C306.26425,127.0796 306.285572,125.78089 305.694037,124.717025 C305.102503,123.65316 303.988082,122.985951 302.77097,122.96697 C302.733703,122.966337 302.696437,122.966337 302.65917,122.96697 L256.7436,122.96697 Z" id="ad4fbcfa-41b0-45f9-a593-23b6dc3fe165" fill="#FFFFFF" fill-rule="nonzero"></path>
@@ -67,7 +67,7 @@
             <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="#0ea5e9" 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="#11a5e9" 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>

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

@@ -1,17 +1,17 @@
 .code-block {
   position: relative;
   border-radius: 3px;
-  background-color: rgb(var(--sl-color-neutral-50));
+  background-color: var(--sl-color-neutral-50);
   margin-bottom: 1.5rem;
 }
 
 .code-block__preview {
   position: relative;
-  border: solid 1px rgb(var(--sl-color-neutral-200));
+  border: solid 1px var(--sl-color-neutral-200);
   border-bottom: none;
   border-top-left-radius: 3px;
   border-top-right-radius: 3px;
-  background-color: rgb(var(--sl-color-neutral-0));
+  background-color: var(--sl-color-neutral-0);
   min-width: 20rem;
   max-width: 100%;
   padding: 1.5rem 3.25rem 1.5rem 1.5rem;
@@ -39,9 +39,9 @@
   bottom: 0;
   width: 1.75rem;
   font-size: 20px;
-  color: rgb(var(--sl-color-neutral-600));
-  background-color: rgb(var(--sl-color-neutral-0));
-  border-left: solid 1px rgb(var(--sl-color-neutral-200));
+  color: var(--sl-color-neutral-600);
+  background-color: var(--sl-color-neutral-0);
+  border-left: solid 1px var(--sl-color-neutral-200);
   border-top-right-radius: 3px;
   cursor: ew-resize;
   transition: 250ms background-color;
@@ -58,10 +58,9 @@
 }
 
 .code-block__source {
-  border: solid 1px rgb(var(--sl-color-neutral-200));
+  border: solid 1px var(--sl-color-neutral-200);
   border-bottom: none;
   border-radius: 0 !important;
-  margin: 0;
   display: none;
 }
 
@@ -69,9 +68,13 @@
   display: block;
 }
 
+.code-block__source pre {
+  margin: 0;
+}
+
 .code-block__buttons {
   position: relative;
-  border: solid 1px rgb(var(--sl-color-neutral-200));
+  border: solid 1px var(--sl-color-neutral-200);
   border-bottom-left-radius: 3px;
   border-bottom-right-radius: 3px;
   display: flex;
@@ -83,18 +86,31 @@
   min-width: 2.5rem;
   border: none;
   border-radius: 0;
-  background: rgb(var(--sl-color-neutral-0));
+  background: var(--sl-color-neutral-0);
   font: inherit;
   font-size: 0.7rem;
   font-weight: 500;
   text-transform: uppercase;
-  color: rgb(var(--sl-color-neutral-600));
+  color: var(--sl-color-neutral-600);
   padding: 0 1rem;
   cursor: pointer;
 }
 
 .code-block__button:not(:last-of-type) {
-  border-right: solid 1px rgb(var(--sl-color-neutral-200));
+  border-right: solid 1px var(--sl-color-neutral-200);
+}
+
+.code-block__button--html,
+.code-block__button--react {
+  width: 70px;
+  display: flex;
+  place-items: center;
+  justify-content: center;
+}
+
+.code-block__button--selected {
+  font-weight: 700;
+  color: var(--sl-color-primary-600);
 }
 
 .code-block__button--codepen {
@@ -113,20 +129,20 @@
 
 .code-block__button:hover,
 .code-block__button:active {
-  box-shadow: 0 0 0 1px rgb(var(--sl-color-primary-400));
+  box-shadow: 0 0 0 1px var(--sl-color-primary-400);
   border-right-color: transparent;
-  background-color: rgb(var(--sl-color-primary-50));
-  color: rgb(var(--sl-color-primary-700));
+  background-color: var(--sl-color-primary-50);
+  color: var(--sl-color-primary-700);
   z-index: 1;
 }
 
 .code-block__button:focus-visible {
   outline: none;
-  color: rgb(var(--sl-color-primary-600));
-  border-color: rgb(var(--sl-color-primary-400));
+  color: var(--sl-color-primary-600);
+  border-color: var(--sl-color-primary-400);
   border-right-color: transparent;
-  background-color: rgb(var(--sl-color-primary-50));
-  box-shadow: 0 0 0 1px rgb(var(--sl-color-primary-400)), var(--sl-focus-ring);
+  background-color: var(--sl-color-primary-50);
+  box-shadow: 0 0 0 1px var(--sl-color-primary-400), var(--sl-focus-ring);
   z-index: 2;
 }
 
@@ -137,7 +153,7 @@
   align-items: center;
   justify-content: center;
   width: 100%;
-  color: rgb(var(--sl-color-neutral-600));
+  color: var(--sl-color-neutral-600);
   cursor: pointer;
   -webkit-appearance: none;
 }
@@ -156,7 +172,7 @@
 .markdown-section .docsify-copy-code-button {
   top: 4px;
   right: 4px;
-  background-color: rgb(var(--sl-color-neutral-600));
+  background-color: var(--sl-color-neutral-500);
   border-radius: var(--sl-border-radius-medium);
   font-family: var(--sl-font-sans);
   font-size: var(--sl-font-size-x-small);
@@ -169,7 +185,7 @@
 
 .markdown-section .docsify-copy-code-button.copied {
   animation: pulse 0.75s;
-  --pulse-color: rgb(var(--sl-color-neutral-600));
+  --pulse-color: var(--sl-color-neutral-600);
 }
 
 @keyframes pulse {
@@ -194,10 +210,19 @@
 }
 
 .markdown-section .docsify-copy-code-button:focus-visible {
-  box-shadow: 0 0 0 3px rgb(var(--sl-color-neutral-500) / 50%);
+  box-shadow: var(--sl-focus-ring);
 }
 
 .markdown-section .docsify-copy-code-button:active {
-  background-color: rgb(var(--sl-color-neutral-600));
+  background-color: var(--sl-color-neutral-600);
   transform: scale(0.92);
 }
+
+/* We can apply data-flavor="html|react" to any element on the page to toggle it when the user's flavor changes */
+body.flavor-html [data-flavor]:not([data-flavor='html']) {
+  display: none;
+}
+
+body.flavor-react [data-flavor]:not([data-flavor='react']) {
+  display: none;
+}

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

@@ -1,10 +1,42 @@
+/* global Prism */
+
 (() => {
+  const reactVersion = '17.0.2';
+  let flavor = getFlavor();
   let count = 1;
 
+  // Sync flavor UI on page load
+  setFlavor(getFlavor());
+
   if (!window.$docsify) {
     throw new Error('Docsify must be loaded before installing this plugin.');
   }
 
+  function convertModuleLinks(html) {
+    const version = sessionStorage.getItem('sl-version');
+
+    html = html
+      .replace(/@shoelace-style\/shoelace/g, `https://cdn.skypack.dev/@shoelace-style/shoelace@${version}`)
+      .replace(/from 'react'/g, `from 'https://cdn.skypack.dev/react@${reactVersion}'`)
+      .replace(/from "react"/g, `from "https://cdn.skypack.dev/react@${reactVersion}"`);
+
+    return html;
+  }
+
+  function getAdjacentExample(name, pre) {
+    let currentPre = pre.nextElementSibling;
+
+    while (currentPre?.tagName.toLowerCase() === 'pre') {
+      if (currentPre?.getAttribute('data-lang').split(' ').includes(name)) {
+        return currentPre;
+      }
+
+      currentPre = currentPre.nextElementSibling;
+    }
+
+    return null;
+  }
+
   function runScript(script) {
     const newScript = document.createElement('script');
 
@@ -18,46 +50,78 @@
     script.parentNode.replaceChild(newScript, script);
   }
 
-  function wrap(el, wrapper) {
-    el.parentNode.insertBefore(wrapper, el);
-    wrapper.appendChild(el);
+  function getFlavor() {
+    return localStorage.getItem('flavor') || 'html';
   }
 
-  window.$docsify.plugins.push((hook, vm) => {
+  function setFlavor(newFlavor) {
+    flavor = ['html', 'react'].includes(newFlavor) ? newFlavor : 'html';
+    localStorage.setItem('flavor', flavor);
+
+    // Set the flavor class on the body
+    document.body.classList.toggle('flavor-html', flavor === 'html');
+    document.body.classList.toggle('flavor-react', flavor === 'react');
+  }
+
+  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');
-      const codePenButton = `
-      <button type="button" class="code-block__button code-block__button--codepen" title="Edit on CodePen">
-        <svg
-          width="138"
-          height="26"
-          viewBox="0 0 138 26"
-          fill="none"
-          stroke="currentColor"
-          stroke-width="2.3"
-          stroke-linecap="round"
-          stroke-linejoin="round"
+
+      const htmlButton = `
+        <button
+          type="button"
+          title="Show HTML code"
+          class="code-block__button code-block__button--html ${flavor === 'html' ? 'code-block__button--selected' : ''}"
         >
-          <path d="M80 6h-9v14h9 M114 6h-9 v14h9 M111 13h-6 M77 13h-6 M122 20V6l11 14V6 M22 16.7L33 24l11-7.3V9.3L33 2L22 9.3V16.7z M44 16.7L33 9.3l-11 7.4 M22 9.3l11 7.3 l11-7.3 M33 2v7.3 M33 16.7V24 M88 14h6c2.2 0 4-1.8 4-4s-1.8-4-4-4h-6v14 M15 8c-1.3-1.3-3-2-5-2c-4 0-7 3-7 7s3 7 7 7 c2 0 3.7-0.8 5-2 M64 13c0 4-3 7-7 7h-5V6h5C61 6 64 9 64 13z" />
-        </svg>
-      </button>
-    `;
+          HTML
+        </button>
+      `;
 
-      [...doc.querySelectorAll('code[class^="lang-"]')].map(code => {
+      const reactButton = `
+        <button
+          type="button"
+          title="Show React code"
+          class="code-block__button code-block__button--react ${
+            flavor === 'react' ? 'code-block__button--selected' : ''
+          }"
+        >
+          React
+        </button>
+      `;
+
+      const codePenButton = `
+        <button type="button" class="code-block__button code-block__button--codepen" title="Edit on CodePen">
+          <svg
+            width="138"
+            height="26"
+            viewBox="0 0 138 26"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2.3"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+          >
+            <path d="M80 6h-9v14h9 M114 6h-9 v14h9 M111 13h-6 M77 13h-6 M122 20V6l11 14V6 M22 16.7L33 24l11-7.3V9.3L33 2L22 9.3V16.7z M44 16.7L33 9.3l-11 7.4 M22 9.3l11 7.3 l11-7.3 M33 2v7.3 M33 16.7V24 M88 14h6c2.2 0 4-1.8 4-4s-1.8-4-4-4h-6v14 M15 8c-1.3-1.3-3-2-5-2c-4 0-7 3-7 7s3 7 7 7 c2 0 3.7-0.8 5-2 M64 13c0 4-3 7-7 7h-5V6h5C61 6 64 9 64 13z" />
+          </svg>
+        </button>
+      `;
+
+      [...doc.querySelectorAll('code[class^="lang-"]')].forEach(code => {
         if (code.classList.contains('preview')) {
+          const isExpanded = code.classList.contains('expanded');
           const pre = code.closest('pre');
-          const preId = `code-block-preview-${count}`;
+          const sourceGroupId = `code-block-source-group-${count}`;
           const toggleId = `code-block-toggle-${count}`;
+          const reactPre = getAdjacentExample('react', pre);
+          const hasReact = reactPre !== null;
 
-          pre.id = preId;
-          pre.classList.add('code-block__source');
           pre.setAttribute('data-lang', pre.getAttribute('data-lang').replace(/ preview$/, ''));
           pre.setAttribute('aria-labelledby', toggleId);
 
           const codeBlock = `
-            <div class="code-block">
+            <div class="code-block ${isExpanded ? 'code-block--expanded' : ''}">
               <div class="code-block__preview">
                 ${code.textContent}
                 <div class="code-block__resizer">
@@ -65,11 +129,32 @@
                 </div>
               </div>
 
-              ${pre.outerHTML}
+              <div class="code-block__source-group" id="${sourceGroupId}">
+                <div class="code-block__source code-block__source--html" ${hasReact ? 'data-flavor="html"' : ''}>
+                  ${pre.outerHTML}
+                </div>
+
+                ${
+                  hasReact
+                    ? `
+                  <div class="code-block__source code-block__source--react" data-flavor="react">
+                    ${reactPre.outerHTML}
+                  </div>
+                `
+                    : ''
+                }
+              </div>
 
               <div class="code-block__buttons">
-                <button type="button" class="code-block__button code-block__toggle" aria-expanded="false" aria-controls="${preId}">
-                  View Source
+                ${hasReact ? ` ${htmlButton} ${reactButton} ` : ''}
+
+                <button
+                  type="button"
+                  class="code-block__button code-block__toggle"
+                  aria-expanded="${isExpanded ? 'true' : 'false'}"
+                  aria-controls="${sourceGroupId}"
+                >
+                  Source
                   <svg
                     viewBox="0 0 24 24"
                     fill="none"
@@ -88,11 +173,15 @@
           `;
 
           pre.replaceWith(domParser.parseFromString(codeBlock, 'text/html').body);
+          reactPre?.remove();
 
           count++;
         }
       });
 
+      // Force the highlighter to run again so JSX fields get highlighted properly
+      requestAnimationFrame(() => Prism.highlightAll());
+
       next(doc.body.innerHTML);
     });
 
@@ -103,12 +192,12 @@
 
     // 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');
@@ -117,21 +206,23 @@
           document.documentElement.addEventListener('touchmove', dragMove, false);
           document.documentElement.addEventListener('mouseup', dragStop, false);
           document.documentElement.addEventListener('touchend', dragStop, false);
-        };
+        }
 
-        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);
-        };
+        }
 
-        const setWidth = width => (preview.style.width = width + 'px');
+        function setWidth(width) {
+          preview.style.width = `${width}px`;
+        }
 
         resizer.addEventListener('mousedown', dragStart);
         resizer.addEventListener('touchstart', dragStart);
@@ -139,49 +230,27 @@
     });
   });
 
-  // Open in CodePen
+  // Toggle source mode
   document.addEventListener('click', event => {
     const button = event.target.closest('button');
 
-    if (button?.classList.contains('code-block__button--codepen')) {
-      const codeBlock = button.closest('.code-block');
-      const html = codeBlock.querySelector('.code-block__source > code').textContent;
-      const version = sessionStorage.getItem('sl-version');
-
-      const form = document.createElement('form');
-      form.action = 'https://codepen.io/pen/define';
-      form.method = 'POST';
-      form.target = '_blank';
-
-      // Docs: https://blog.codepen.io/documentation/prefill/
-      const data = {
-        title: '',
-        description: '',
-        tags: ['shoelace', 'web components'],
-        editors: '100',
-        head: `<meta name="viewport" content="width=device-width">`,
-        css_external: ``,
-        js_external: ``,
-        js_module: true,
-        html:
-          `<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${version}/dist/themes/light.css">\n` +
-          `<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${version}/dist/shoelace.js"></script>\n` +
-          `\n` +
-          html,
-        css: `body {\n  font: 16px sans-serif;\n}`,
-        js: ``
-      };
-
-      const input = document.createElement('input');
-      input.type = 'hidden';
-      input.name = 'data';
-      input.value = JSON.stringify(data);
-      form.append(input);
-
-      document.body.append(form);
-      form.submit();
-      form.remove();
+    if (button?.classList.contains('code-block__button--html')) {
+      setFlavor('html');
+    } else if (button?.classList.contains('code-block__button--react')) {
+      setFlavor('react');
+    } else {
+      return;
     }
+
+    // Update flavor buttons
+    [...document.querySelectorAll('.code-block')].forEach(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');
+    });
   });
 
   // Expand and collapse code blocks
@@ -205,4 +274,92 @@
       });
     }
   });
+
+  // Open in CodePen
+  document.addEventListener('click', event => {
+    const button = event.target.closest('button');
+    const version = sessionStorage.getItem('sl-version');
+
+    if (button?.classList.contains('code-block__button--codepen')) {
+      const codeBlock = button.closest('.code-block');
+      const htmlExample = codeBlock.querySelector('.code-block__source--html > pre > code')?.textContent;
+      const reactExample = codeBlock.querySelector('.code-block__source--react > pre > code')?.textContent;
+      const isReact = flavor === 'react' && typeof reactExample === 'string';
+      const theme = localStorage.getItem('theme');
+      const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+      const isDark = theme === 'dark' || (theme === 'auto' && prefersDark);
+      const editors = isReact ? '0010' : '1000';
+      let htmlTemplate = '';
+      let jsTemplate = '';
+      let cssTemplate = '';
+
+      const form = document.createElement('form');
+      form.action = 'https://codepen.io/pen/define';
+      form.method = 'POST';
+      form.target = '_blank';
+
+      // HTML templates
+      if (!isReact) {
+        htmlTemplate =
+          `<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${version}/dist/shoelace.js"></script>\n` +
+          `\n${htmlExample}`;
+        jsTemplate = '';
+      }
+
+      // React templates
+      if (isReact) {
+        htmlTemplate = '<div id="root"></div>';
+        jsTemplate =
+          `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` +
+          `// Set the base path for Shoelace assets\n` +
+          `setBasePath('https://cdn.skypack.dev/@shoelace-style/shoelace@${version}/dist/')\n` +
+          `\n${convertModuleLinks(reactExample)}\n` +
+          `\n` +
+          `ReactDOM.render(<App />, document.getElementById('root'));`;
+      }
+
+      // CSS templates
+      cssTemplate =
+        `@import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${version}/dist/themes/${
+          isDark ? 'dark' : 'light'
+        }.css';\n` +
+        '\n' +
+        'body {\n' +
+        '  font: 16px sans-serif;\n' +
+        '  background-color: var(--sl-color-neutral-0);\n' +
+        '  color: var(--sl-color-neutral-900);\n' +
+        '  padding: 1rem;\n' +
+        '}';
+
+      // Docs: https://blog.codepen.io/documentation/prefill/
+      const data = {
+        title: '',
+        description: '',
+        tags: ['shoelace', 'web components'],
+        editors,
+        head: `<meta name="viewport" content="width=device-width">`,
+        html_classes: `sl-theme-${isDark ? 'dark' : 'light'}`,
+        css_external: ``,
+        js_external: ``,
+        js_module: true,
+        js_pre_processor: isReact ? 'babel' : 'none',
+        html: htmlTemplate,
+        css: cssTemplate,
+        js: jsTemplate
+      };
+
+      const input = document.createElement('input');
+      input.type = 'hidden';
+      input.name = 'data';
+      input.value = JSON.stringify(data);
+      form.append(input);
+
+      document.body.append(form);
+      form.submit();
+      form.remove();
+    }
+  });
 })();

docs/assets/plugins/metadata/metadata.js

@@ -29,7 +29,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)}
@@ -67,7 +67,8 @@
     table.innerHTML = `
       <thead>
         <tr>
-          <th>Name</th>
+          <th data-flavor="html">Name</th>
+          <th data-flavor="react">React Event</th>
           <th>Description</th>
           <th>Event Detail</th>
         </tr>
@@ -77,7 +78,8 @@
           .map(
             event => `
               <tr>
-                <td><code class="nowrap">${escapeHtml(event.name)}</code></td>
+                <td data-flavor="html"><code class="nowrap">${escapeHtml(event.name)}</code></td>
+                <td data-flavor="react"><code class="nowrap">${escapeHtml(event.reactName)}</code></td>
                 <td>${escapeHtml(event.description)}</td>
                 <td>${event.type?.text ? `<code>${escapeHtml(event.type?.text)}` : '-'}</td>
               </tr>
@@ -161,6 +163,7 @@
         <tr>
           <th>Name</th>
           <th>Description</th>
+          <th>Default</th>
         </tr>
       </thead>
       <tbody>
@@ -168,8 +171,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>
             `
           )
@@ -236,23 +240,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);
@@ -262,7 +266,11 @@
   }
 
   function escapeHtml(html) {
-    return (html + '')
+    if (!html) {
+      return '';
+    }
+    return html
+      .toString()
       .replace(/&/g, '&amp;')
       .replace(/</g, '&lt;')
       .replace(/>/g, '&gt;')
@@ -273,8 +281,8 @@
 
   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');
@@ -295,8 +303,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');
 
@@ -314,19 +322,19 @@
       buttons.classList.add('sidebar-buttons');
       buttons.innerHTML = `
         <sl-button size="small" class="repo-button repo-button--sponsor" href="https://github.com/sponsors/claviska" target="_blank">
-          <sl-icon name="heart"></sl-icon> Sponsor
+          <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 name="github"></sl-icon> <span class="github-star-count">Star</span>
+          <sl-icon slot="prefix" name="github"></sl-icon> <span class="github-star-count">Star</span>
         </sl-button>
         <sl-button size="small" class="repo-button repo-button--twitter" href="https://twitter.com/shoelace_style" target="_blank">
-          <sl-icon name="twitter"></sl-icon> Follow
+          <sl-icon slot="prefix" name="twitter"></sl-icon> Follow
         </sl-button>
       `;
       target.appendChild(buttons);
     });
 
-    hook.beforeEach(async function (content, next) {
+    hook.beforeEach(async (content, next) => {
       const metadata = await customElements;
 
       // Replace %VERSION% placeholders
@@ -338,15 +346,23 @@
         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">
@@ -355,11 +371,11 @@
             </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>
@@ -375,7 +391,7 @@
         let result = '';
 
         if (!component) {
-          console.error('Component not found in metadata: ' + tag);
+          console.error(`Component not found in metadata: ${tag}`);
           return next(content);
         }
 
@@ -392,6 +408,50 @@
           return prop.kind === 'field' && prop.privacy !== 'private';
         });
 
+        if (component.path) {
+          /* prettier-ignore */
+          result += `
+            ## Importing
+
+            <sl-tab-group>
+            <sl-tab slot="nav" panel="script">Script</sl-tab>
+            <sl-tab slot="nav" panel="import">Import</sl-tab>
+            <sl-tab slot="nav" panel="bundler">Bundler</sl-tab>
+            <sl-tab slot="nav" panel="react">React</sl-tab>
+
+            <sl-tab-panel name="script">\n
+            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>
+            \`\`\`
+            </sl-tab-panel>
+
+            <sl-tab-panel name="import">\n
+            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}';
+            \`\`\`
+            </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}';
+            \`\`\`
+            </sl-tab-panel>
+
+            <sl-tab-panel name="react">\n
+            To import this component as a [React component](/frameworks/react):
+            \`\`\`js
+            import { ${component.name} } from '@shoelace-style/shoelace/dist/react';
+            \`\`\`
+            </sl-tab-panel>
+            </sl-tab-group>
+          `;
+        }
+
         if (props?.length) {
           result += `
             ## Properties
@@ -408,8 +468,20 @@
 
         if (methods?.length) {
           result += `
-          ## Methods
-          ${createMethodsTable(methods)}
+            ## Methods
+
+            <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)}
           `;
         }
 
@@ -453,41 +525,6 @@
           `;
         }
 
-        if (component.path) {
-          /* prettier-ignore */
-          result += `
-            ## Importing
-
-            <sl-tab-group>
-            <sl-tab slot="nav" panel="cdn" active>CDN</sl-tab>
-            <sl-tab slot="nav" panel="bundler">Bundler</sl-tab>
-            <sl-tab slot="nav" panel="react">React</sl-tab>
-
-            <sl-tab-panel name="cdn">\n
-            To import this component from [the CDN](https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace):
-
-            \`\`\`js
-            import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@${metadata.package.version}/${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}';
-            \`\`\`
-            </sl-tab-panel>
-
-            <sl-tab-panel name="react">\n
-            To import this component using [\`@shoelace-style/react\`](https://www.npmjs.com/package/@shoelace-style/react):
-            \`\`\`js
-            import '@shoelace-style/react/dist/${component.tagName.replace(/^sl-/, '')}';
-            \`\`\`
-            </sl-tab-panel>
-            </sl-tab-group>
-          `;
-        }
-
         // Strip whitespace so markdown doesn't process things as code blocks
         return result.replace(/^ +| +$/gm, '');
       });
@@ -496,11 +533,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/lunr.min.js

@@ -323,7 +323,8 @@
         w = new RegExp('([^aeiouylsz])\\1$'),
         Q = new RegExp('^' + n + i + '[^aeiouwxy]$'),
         k = /^(.+?[^aeiou])y$/,
-        S = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/,
+        S =
+          /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/,
         E = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/,
         L = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/,
         b = /^(.+?)(s|t)(ion)$/,

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 */
@@ -30,7 +31,7 @@ body.site-search-visible {
   left: 0;
   right: 0;
   bottom: 0;
-  background: rgb(var(--sl-overlay-background-color) / var(--sl-overlay-opacity));
+  background: var(--sl-overlay-background-color);
   z-index: -1;
 }
 
@@ -39,7 +40,7 @@ body.site-search-visible {
   flex-direction: column;
   max-width: 460px;
   max-height: calc(100vh - 20rem);
-  background-color: rgb(var(--sl-surface-base-alt));
+  background-color: var(--sl-panel-background-color);
   border-radius: var(--sl-border-radius-large);
   box-shadow: var(--sl-shadow-x-large);
   margin: 10rem auto;
@@ -74,7 +75,7 @@ body.site-search-visible {
 }
 
 .site-search--has-results .site-search__body {
-  border-top: solid 1px rgb(var(--sl-color-neutral-200));
+  border-top: solid 1px var(--sl-color-neutral-200);
 }
 
 .site-search__results {
@@ -97,15 +98,22 @@ body.site-search-visible {
 
 .site-search__results li a:hover,
 .site-search__results li a:hover small {
-  background-color: rgb(var(--sl-color-neutral-100));
+  background-color: var(--sl-color-neutral-100);
 }
 
 .site-search__results li[aria-selected='true'] a,
 .site-search__results li[aria-selected='true'] a small,
 .site-search__results li[aria-selected='true'] a sl-icon {
   outline: none;
-  color: rgb(var(--sl-color-neutral-0));
-  background-color: rgb(var(--sl-color-primary-600));
+  color: var(--sl-color-neutral-0);
+  background-color: var(--sl-color-primary-600);
+}
+
+.sl-theme-dark .site-search__results li[aria-selected='true'] a,
+.sl-theme-dark .site-search__results li[aria-selected='true'] a small,
+.sl-theme-dark .site-search__results li[aria-selected='true'] a sl-icon {
+  background-color: var(--sl-color-primary-400);
+  color: var(--sl-color-neutral-1000);
 }
 
 .site-search__results h3 {
@@ -115,7 +123,7 @@ body.site-search-visible {
 
 .site-search__results small {
   display: block;
-  color: rgb(var(--sl-color-neutral-600));
+  color: var(--sl-color-neutral-600);
 }
 
 .site-search__result {
@@ -132,7 +140,7 @@ body.site-search-visible {
 .site-search__result-icon {
   flex: 0 0 auto;
   display: flex;
-  color: rgb(var(--sl-color-neutral-400));
+  color: var(--sl-color-neutral-400);
   font-size: var(--sl-font-size-x-large);
 }
 
@@ -142,7 +150,7 @@ body.site-search-visible {
 
 .site-search__empty {
   display: none;
-  border-top: solid 1px rgb(var(--sl-color-neutral-200));
+  border-top: solid 1px var(--sl-color-neutral-200);
   text-align: center;
   padding: var(--sl-spacing-x-large);
 }
@@ -155,14 +163,14 @@ body.site-search-visible {
   display: flex;
   justify-content: center;
   gap: var(--sl-spacing-large);
-  border-top: solid 1px rgb(var(--sl-color-neutral-200));
+  border-top: solid 1px var(--sl-color-neutral-200);
   border-bottom-left-radius: inherit;
   border-bottom-right-radius: inherit;
   padding: var(--sl-spacing-medium);
 }
 
 .site-search__footer small {
-  color: rgb(var(--sl-color-neutral-700));
+  color: var(--sl-color-neutral-700);
 }
 
 @media screen and (max-width: 900px) {

docs/assets/plugins/search/search.js

@@ -1,11 +1,12 @@
+/* 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');
@@ -76,7 +77,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 +89,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);
@@ -203,7 +203,7 @@
         }
 
         // Update the selected item
-        items.map(item => {
+        items.forEach(item => {
           if (item === nextEl) {
             item.setAttribute('aria-selected', 'true');
             nextEl.scrollIntoView({ block: 'nearest' });
@@ -211,8 +211,6 @@
             item.setAttribute('aria-selected', 'false');
           }
         });
-
-        return;
       }
     }
 
@@ -221,34 +219,40 @@
         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 matches = hasQuery ? searchIndex.search(`t:*${query}*^20 h:*${query}*^10 ${query}~1^5 *${query}*^0`) : [];
+        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';
+          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 = $docsify.routerMode === 'hash' ? `/#/${page.url}` : `/${page.url}`;
+          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>

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) {
@@ -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 => {
@@ -73,11 +72,10 @@
           event.preventDefault();
 
           setTheme(isDark() ? 'light' : 'dark');
-          show();
         }
       });
 
-      // Set the intial theme and sync the UI
+      // Set the initial theme and sync the UI
       setTheme(theme);
     });
   });

docs/assets/styles/docs.css

@@ -13,17 +13,17 @@ body {
   font-size: var(--sl-font-size-medium);
   font-weight: var(--sl-font-weight-normal);
   letter-spacing: var(--sl-letter-spacing-normal);
-  background-color: rgb(var(--sl-surface-base));
-  color: rgb(var(--sl-color-neutral-800));
+  background-color: var(--sl-color-neutral-0);
+  color: var(--sl-color-neutral-900);
   line-height: var(--sl-line-height-normal);
 }
 
 a {
-  color: rgb(var(--sl-color-primary-600));
+  color: var(--sl-color-primary-600);
 }
 
 a:hover {
-  color: rgb(var(--sl-color-primary-700));
+  color: var(--sl-color-primary-700);
 }
 
 strong {
@@ -32,8 +32,8 @@ strong {
 
 /* Sidebar */
 .sidebar {
-  background-color: rgb(var(--sl-surface-base));
-  border-right: solid 1px rgb(var(--sl-color-neutral-200));
+  background-color: var(--sl-color-neutral-0);
+  border-right: solid 1px var(--sl-color-neutral-200);
 }
 
 .sidebar .app-name {
@@ -43,7 +43,7 @@ strong {
 .sidebar-version {
   font-size: var(--sl-font-size-x-small);
   font-weight: var(--sl-font-weight-normal);
-  color: rgb(var(--sl-color-neutral-500));
+  color: var(--sl-color-neutral-500);
   text-align: right;
   padding: 0 var(--sl-spacing-small);
   margin: -1.25rem 0 0.6rem 0;
@@ -61,7 +61,7 @@ strong {
   width: 2rem;
   height: 2rem;
   border-radius: var(--sl-border-radius-medium);
-  background-color: rgb(var(--sl-surface-base));
+  background-color: var(--sl-color-neutral-0);
   padding: 0.5rem;
 }
 
@@ -70,7 +70,7 @@ strong {
 }
 
 .sidebar-toggle:active .sidebar-toggle-button span {
-  background-color: rgb(var(--sl-color-primary-600));
+  background-color: var(--sl-color-primary-600);
 }
 
 .sidebar-toggle:focus {
@@ -110,12 +110,12 @@ strong {
 
 .sidebar-nav li.collapse > a,
 .sidebar-nav li.active > a {
-  color: rgb(var(--sl-color-primary-600));
+  color: var(--sl-color-primary-600);
 }
 
 .sidebar li > p {
   font-weight: var(--sl-font-weight-bold);
-  border-bottom: solid 1px rgb(var(--sl-color-neutral-200));
+  border-bottom: solid 1px var(--sl-color-neutral-200);
   margin: 0 0.75rem 0.5rem 0;
 }
 
@@ -197,16 +197,15 @@ strong {
 
 .markdown-section {
   max-width: 860px;
-  overflow-anchor: none;
 }
 
 .anchor span {
-  color: rgb(var(--sl-color-neutral-1000));
+  color: var(--sl-color-neutral-1000);
 }
 
 .markdown-section blockquote {
   position: relative;
-  border-left: solid 4px rgb(var(--sl-color-neutral-200));
+  border-left: solid 4px var(--sl-color-neutral-200);
   font-style: italic;
   padding: 1rem 1.5rem;
   margin: 0 0 1rem 0;
@@ -230,7 +229,7 @@ strong {
 }
 
 .docsify-pagination-container {
-  border-top-color: rgb(var(--sl-color-neutral-200)) !important;
+  border-top-color: var(--sl-color-neutral-200) !important;
 }
 
 .pagination-item-label,
@@ -255,7 +254,7 @@ strong {
 
 .markdown-section h2 {
   font-size: var(--sl-font-size-x-large);
-  border-bottom: solid 1px rgb(var(--sl-color-neutral-200));
+  border-bottom: solid 1px var(--sl-color-neutral-200);
   margin-top: 2rem;
 }
 
@@ -286,30 +285,30 @@ strong {
 .markdown-section code {
   font-family: var(--sl-font-mono);
   font-size: 87.5%;
-  background-color: rgb(var(--sl-color-neutral-50));
+  background-color: var(--sl-color-neutral-50);
   border-radius: var(--sl-border-radius-small);
   padding: 2px 4px;
 }
 
 .markdown-section tr:nth-child(2n) code {
-  background-color: rgb(var(--sl-color-neutral-100));
+  background-color: var(--sl-color-neutral-100);
 }
 
 kbd,
 .markdown-section kbd {
   font-family: var(--sl-font-mono);
   font-size: 87.5%;
-  background-color: rgb(var(--sl-color-neutral-50));
+  background-color: var(--sl-color-neutral-50);
   border-radius: var(--sl-border-radius-small);
-  border: solid 1px rgb(var(--sl-color-neutral-200));
-  box-shadow: inset 0 1px 0 rgb(var(--sl-color-neutral-0));
+  border: solid 1px var(--sl-color-neutral-200);
+  box-shadow: inset 0 1px 0 var(--sl-color-neutral-0);
   padding: 2px 5px;
 }
 
 /* Code blocks */
 .markdown-section pre {
   position: relative;
-  background-color: rgb(var(--sl-color-neutral-50));
+  background-color: var(--sl-color-neutral-50);
   border-radius: var(--sl-border-radius-medium);
 }
 
@@ -317,7 +316,7 @@ kbd,
   display: block;
   background: none;
   border-radius: 0;
-  color: rgb(var(--sl-color-neutral-800));
+  color: var(--sl-color-neutral-800);
   padding: var(--sl-spacing-medium);
   overflow: auto;
   hyphens: none;
@@ -325,18 +324,18 @@ kbd,
 }
 
 .markdown-section pre .token.comment {
-  color: rgb(var(--sl-color-neutral-500));
+  color: var(--sl-color-neutral-500);
 }
 
 .markdown-section pre .token.prolog,
 .markdown-section pre .token.doctype,
 .markdown-section pre .token.cdata,
 .markdown-section pre .token.operator {
-  color: rgb(var(--sl-color-neutral-600));
+  color: var(--sl-color-neutral-600);
 }
 
 .markdown-section pre .token.punctuation {
-  color: rgb(var(--sl-color-neutral-600));
+  color: var(--sl-color-neutral-600);
 }
 
 .namespace {
@@ -347,12 +346,12 @@ kbd,
 .markdown-section pre .token.keyword,
 .markdown-section pre .token.tag,
 .markdown-section pre .token.url {
-  color: rgb(var(--sl-color-sky-600));
+  color: var(--sl-color-blue-600);
 }
 
 .markdown-section pre .token.symbol,
 .markdown-section pre .token.deleted {
-  color: rgb(var(--sl-color-pink-600));
+  color: var(--sl-color-pink-600);
 }
 
 .markdown-section pre .token.boolean,
@@ -363,24 +362,24 @@ kbd,
 .markdown-section pre .token.char,
 .markdown-section pre .token.builtin,
 .markdown-section pre .token.inserted {
-  color: rgb(var(--sl-color-emerald-600));
+  color: var(--sl-color-emerald-600);
 }
 
 .markdown-section pre .token.atrule,
 .markdown-section pre .token.attr-value,
 .markdown-section pre .token.number,
 .markdown-section pre .token.variable {
-  color: rgb(var(--sl-color-violet-600));
+  color: var(--sl-color-violet-700);
 }
 
 .markdown-section pre .token.function,
 .markdown-section pre .token.class-name,
 .markdown-section pre .token.regex {
-  color: rgb(var(--sl-color-orange-600));
+  color: var(--sl-color-orange-600);
 }
 
 .markdown-section pre .token.important {
-  color: rgb(var(--sl-color-red-600));
+  color: var(--sl-color-red-600);
 }
 
 .markdown-section pre .token.important,
@@ -413,7 +412,7 @@ kbd,
 }
 
 .markdown-section tr:nth-child(2n) {
-  background: rgb(var(--sl-color-neutral-50));
+  background: var(--sl-color-neutral-50);
 }
 
 .markdown-section th {
@@ -423,8 +422,8 @@ kbd,
 }
 
 .markdown-section td {
-  border-top: solid 1px rgb(var(--sl-color-neutral-200));
-  border-bottom: solid 1px rgb(var(--sl-color-neutral-200));
+  border-top: solid 1px var(--sl-color-neutral-200);
+  border-bottom: solid 1px var(--sl-color-neutral-200);
   border-left: none;
   border-right: none;
 }
@@ -434,7 +433,7 @@ kbd,
 }
 
 .markdown-section table sl-tooltip code {
-  border-bottom: dashed 1px rgb(var(--sl-color-neutral-300));
+  border-bottom: dashed 1px var(--sl-color-neutral-300);
   cursor: help;
 }
 
@@ -447,7 +446,7 @@ kbd,
 .markdown-section p.tip,
 .markdown-section p.warn {
   position: relative;
-  background-color: rgb(var(--sl-color-neutral-50));
+  background-color: var(--sl-color-neutral-50);
   border-left: solid 4px transparent;
   border-radius: var(--sl-border-radius-medium);
   padding-left: 1.5rem;
@@ -457,7 +456,7 @@ kbd,
 .markdown-section p.warn:before {
   content: '!';
   border-radius: 100%;
-  color: rgb(var(--sl-color-neutral-0));
+  color: var(--sl-color-neutral-0);
   font-size: 14px;
   font-weight: bold;
   left: -12px;
@@ -470,29 +469,29 @@ kbd,
 }
 
 .markdown-section p.warn {
-  border-left-color: rgb(var(--sl-color-primary-600));
+  border-left-color: var(--sl-color-primary-600);
 }
 
 .markdown-section p.warn:before {
-  background-color: rgb(var(--sl-color-primary-600));
+  background-color: var(--sl-color-primary-600);
 }
 
 .markdown-section p.tip {
-  border-left-color: rgb(var(--sl-color-danger-600));
+  border-left-color: var(--sl-color-danger-600);
 }
 
 .markdown-section p.tip:before {
-  background-color: rgb(var(--sl-color-danger-600));
+  background-color: var(--sl-color-danger-600);
 }
 
 .markdown-section p.tip code,
 .markdown-section p.warn code {
-  background-color: rgb(var(--sl-color-neutral-100));
+  background-color: var(--sl-color-neutral-100);
 }
 
 /* Component headers */
 .component-header {
-  border-bottom: solid 1px rgb(var(--sl-color-neutral-200));
+  border-bottom: solid 1px var(--sl-color-neutral-200);
   padding-bottom: 2rem;
   margin-top: -1rem;
   margin-bottom: 2rem;
@@ -506,7 +505,7 @@ kbd,
 
 .markdown-section .component-header__tag code {
   background: none;
-  color: rgb(var(--sl-color-neutral-600));
+  color: var(--sl-color-neutral-600);
   font-size: var(--sl-font-size-large);
   padding: 0;
   margin: 0;
@@ -524,15 +523,15 @@ kbd,
 
 /* Repo buttons */
 .repo-button--sponsor sl-icon {
-  color: rgb(var(--sl-color-pink-600));
+  color: var(--sl-color-pink-600);
 }
 
 .repo-button--github sl-icon {
-  color: rgb(var(--sl-color-neutral-700));
+  color: var(--sl-color-neutral-700);
 }
 
 .repo-button--twitter sl-icon {
-  color: rgb(var(--sl-color-sky-500));
+  color: var(--sl-color-sky-500);
 }
 
 @media screen and (max-width: 400px) {
@@ -551,13 +550,13 @@ body[data-page^='/tokens/'] .table-wrapper td:first-child code {
 .border-radius-demo {
   width: 3rem;
   height: 3rem;
-  background: rgb(var(--sl-color-primary-600));
+  background: var(--sl-color-primary-600);
 }
 
 /* Transition demo */
 .transition-demo {
   position: relative;
-  background: rgb(var(--sl-color-neutral-200));
+  background: var(--sl-color-neutral-200);
   width: 8rem;
   height: 2rem;
 }
@@ -565,7 +564,7 @@ body[data-page^='/tokens/'] .table-wrapper td:first-child code {
 .transition-demo:after {
   content: '';
   position: absolute;
-  background-color: rgb(var(--sl-color-primary-600));
+  background-color: var(--sl-color-primary-600);
   top: 0;
   left: 0;
   width: 0;
@@ -581,10 +580,10 @@ body[data-page^='/tokens/'] .table-wrapper td:first-child code {
 /* Spacing demo */
 .spacing-demo {
   width: 100px;
-  background: rgb(var(--sl-color-primary-600));
+  background: var(--sl-color-primary-600);
 }
 
-/* Elevation dmeo */
+/* Elevation demo */
 .elevation-demo {
   background: transparent;
   border-radius: 3px;
@@ -623,7 +622,7 @@ body[data-page^='/tokens/'] .table-wrapper td:first-child code {
 }
 
 .color-palette__swatch--border {
-  box-shadow: inset 0 0 0 1px rgb(var(--sl-color-neutral-1000) / 10%);
+  box-shadow: inset 0 0 0 1px var(--sl-color-neutral-300);
 }
 
 @media screen and (max-width: 1200px) {

docs/components/alert.md

@@ -2,7 +2,7 @@
 
 [component-header:sl-alert]
 
-Alerts are used to display important messages either inline or as toast notifications.
+Alerts are used to display important messages inline or as toast notifications.
 
 ```html preview
 <sl-alert open>
@@ -11,16 +11,27 @@ Alerts are used to display important messages either inline or as toast notifica
 </sl-alert>
 ```
 
+```jsx react
+import { SlAlert, SlIcon } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlAlert open>
+    <SlIcon slot="icon" name="info-circle" />
+    This is a standard alert. You can customize its content and even the icon.
+  </SlAlert>
+);
+```
+
 ?> Alerts will not be visible if the `open` attribute is not present.
 
 ## 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>
   You can tell by how pretty the alert is.
@@ -28,7 +39,7 @@ Set the `type` attribute to change the alert's type.
 
 <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>
   You can safely exit the app now.
@@ -36,7 +47,7 @@ Set the `type` attribute to change the alert's type.
 
 <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>
   Settings will take affect on next login.
@@ -44,7 +55,7 @@ Set the `type` attribute to change the alert's type.
 
 <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>
   Please login again to continue.
@@ -52,19 +63,65 @@ Set the `type` attribute to change the alert's type.
 
 <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!
 </sl-alert>
 ```
 
+```jsx react
+import { SlAlert, SlIcon } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlAlert variant="primary" open>
+      <SlIcon slot="icon" name="info-circle" />
+      <strong>This is super informative</strong><br />
+      You can tell by how pretty the alert is.
+    </SlAlert>
+
+    <br />
+
+    <SlAlert variant="success" open>
+      <SlIcon slot="icon" name="check2-circle" />
+      <strong>Your changes have been saved</strong><br />
+      You can safely exit the app now.
+    </SlAlert>
+
+    <br />
+
+    <SlAlert variant="neutral" open>
+      <SlIcon slot="icon" name="gear" />
+      <strong>Your settings have been updated</strong><br />
+      Settings will take affect on next login.
+    </SlAlert>
+
+    <br />
+
+    <SlAlert variant="warning" open>
+      <SlIcon slot="icon" name="exclamation-triangle" />
+      <strong>Your session has ended</strong><br />
+      Please login again to continue.
+    </SlAlert>
+
+    <br />
+
+    <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!
+    </SlAlert>
+  </>
+);
+```
+
 ### Closable
 
 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>
@@ -77,25 +134,60 @@ Add the `closable` attribute to show a close button that will hide the alert.
 </script>
 ```
 
+```jsx react
+import { useState } from 'react';
+import { SlAlert, SlIcon } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [open, setOpen] = useState(true);
+
+  function handleHide() {
+    setOpen(false);
+    setTimeout(() => setOpen(true), 2000);
+  }
+
+  return (
+    <SlAlert 
+      open={open}
+      closable
+      onSlAfterHide={handleHide}
+    >
+      <SlIcon slot="icon" name="info-circle" />
+      You can close this alert any time!
+    </SlAlert>
+  );
+};
+```
+
 ### Without Icons
 
 Icons are optional. Simply omit the `icon` slot if you don't want them.
 
 ```html preview
-<sl-alert type="primary" open>
+<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 variant="primary" open>
+    Nothing fancy here, just a simple alert.
+  </SlAlert>
+);
+```
+
 ### Duration
 
 Set the `duration` attribute to automatically hide an alert after a period of time. This is useful for alerts that don't require acknowledgement.
 
 ```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>
@@ -116,6 +208,46 @@ Set the `duration` attribute to automatically hide an alert after a period of ti
 </style>
 ```
 
+```jsx react
+import { useState } from 'react';
+import {
+  SlAlert,
+  SlButton,
+  SlIcon
+} from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .alert-duration sl-alert {
+    margin-top: var(--sl-spacing-medium);
+  }
+`;
+
+const App = () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <div className="alert-duration">
+        <SlButton variant="primary" onClick={() => setOpen(true)}>Show Alert</SlButton>
+
+        <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>
+      </div>
+
+      <style>{css}</style>
+    </>
+  );
+};
+```
+
 ### Toast Notifications
 
 To display an alert as a toast notification, or "toast", create the alert and call its `toast()` method. This will move the alert out of its position in the DOM and into [the toast stack](#the-toast-stack) where it will be shown. Once dismissed, it will be removed from the DOM completely. To reuse a toast, store a reference to it and call `toast()` again later on.
@@ -124,37 +256,37 @@ 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-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 type="primary" duration="3000" closable>
+  <sl-alert variant="primary" duration="3000" closable>
     <sl-icon slot="icon" name="info-circle"></sl-icon>
     <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>
     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>
     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>
     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>
     We're very sorry to see you go!
@@ -164,22 +296,97 @@ 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());
   });
 </script>
 ```
 
+```jsx react
+import { useRef } from 'react';
+import {
+  SlAlert,
+  SlButton,
+  SlIcon
+} from '@shoelace-style/shoelace/dist/react';
+
+function showToast(alert) {
+  alert.toast();
+}
+
+const App = () => {
+  const primary = useRef(null);
+  const success = useRef(null);
+  const neutral = useRef(null);
+  const warning = useRef(null);
+  const danger = useRef(null);
+
+  return (
+    <>
+      <SlButton variant="primary" onClick={() => primary.current.toast()}>
+        Primary
+      </SlButton>
+
+      <SlButton variant="success" onClick={() => success.current.toast()}>
+        Success
+      </SlButton>
+
+      <SlButton variant="neutral" onClick={() => neutral.current.toast()}>
+        Neutral
+      </SlButton>
+
+      <SlButton variant="warning" onClick={() => warning.current.toast()}>
+        Warning
+      </SlButton>
+
+      <SlButton variant="danger" onClick={() => danger.current.toast()}>
+        Danger
+      </SlButton>
+
+      <SlAlert ref={primary} variant="primary" duration="3000" closable>
+        <SlIcon slot="icon" name="info-circle" />
+        <strong>This is super informative</strong><br />
+        You can tell by how pretty the alert is.
+      </SlAlert>
+
+      <SlAlert ref={success} variant="success" duration="3000" closable>
+        <SlIcon slot="icon" name="check2-circle" />
+        <strong>Your changes have been saved</strong><br />
+        You can safely exit the app now.
+      </SlAlert>
+
+      <SlAlert ref={neutral} variant="neutral" duration="3000" closable>
+        <SlIcon slot="icon" name="gear" />
+        <strong>Your settings have been updated</strong><br />
+        Settings will take affect on next login.
+      </SlAlert>
+
+      <SlAlert ref={warning} variant="warning" duration="3000" closable>
+        <SlIcon slot="icon" name="exclamation-triangle" />
+        <strong>Your session has ended</strong><br />
+        Please login again to continue.
+      </SlAlert>
+
+      <SlAlert ref={danger} variant="danger" duration="3000" closable>
+        <SlIcon slot="icon" name="exclamation-octagon" />
+        <strong>Your account has been deleted</strong><br />
+        We're very sorry to see you go!
+      </SlAlert>
+    </>
+  );
+};
+```
+
 ### Creating Toasts Imperatively
 
 For convenience, you can create a utility that emits toast notifications with a function call rather than composing them in your HTML. To do this, generate the alert with JavaScript, append it to the body, and call the `toast()` method as shown in the example below.
 
 ```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>
@@ -195,9 +402,9 @@ For convenience, you can create a utility that emits toast notifications with a
   }  
 
   // 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

@@ -6,11 +6,24 @@ A component for displaying animated GIFs and WEBPs that play and pause on intera
 
 ```html preview
 <sl-animated-image 
-  src="/assets/images/walk.gif" 
+  src="https://shoelace.style/assets/images/walk.gif" 
   alt="Animation of untied shoes walking on pavement"
 ></sl-animated-image>
 ```
 
+```jsx react
+import { SlAnimatedImage } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlAnimatedImage
+    src="https://shoelace.style/assets/images/walk.gif" 
+    alt="Animation of untied shoes walking on pavement"
+  />
+);
+```
+
+?> This component uses `<canvas>` to draw freeze frames, so images are subject to [cross-origin restrictions](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_enabled_image).
+
 ## Examples
 
 ### WEBP Images
@@ -19,31 +32,54 @@ Both GIF and WEBP images are supported.
 
 ```html preview
 <sl-animated-image 
-  src="/assets/images/tie.webp" 
+  src="https://shoelace.style/assets/images/tie.webp" 
   alt="Animation of a shoe being tied"
 ></sl-animated-image>
 ```
 
+```jsx react
+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"
+  />
+);
+```
+
 ### Setting a Width and Height
 
 To set a custom size, apply a width and/or height to the host element.
 
 ```html preview
 <sl-animated-image 
-  src="/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;"
 >
 </sl-animated-image>
 ```
 
+```jsx react
+import { SlAnimatedImage } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlAnimatedImage
+    src="https://shoelace.style/assets/images/walk.gif" 
+    alt="Animation of untied shoes walking on pavement"
+    style={{ width: '150px', height: '200px' }}
+  />
+);
+```
+
 ### Customizing the Control Box
 
 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="/assets/images/walk.gif" 
+  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>
@@ -55,9 +91,38 @@ You can change the appearance and location of the control box by targeting the `
     bottom: 1rem;
     left: 1rem;
     background-color: deeppink;
-    color: white;
+    border: none;
+    color: pink;
   }
 </style>
 ```
 
+```jsx react
+import { SlAnimatedImage } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .animated-image-custom-control-box::part(control-box) {
+    top: auto;
+    right: auto;
+    bottom: 1rem;
+    left: 1rem;
+    background-color: deeppink;
+    border: none;
+    color: pink;
+  }
+`;
+
+const App = () => (
+  <>
+    <SlAnimatedImage
+      className="animated-image-custom-control-box"
+      src="https://shoelace.style/assets/images/walk.gif" 
+      alt="Animation of untied shoes walking on pavement"
+    />
+
+    <style>{css}</style>
+  </>
+);
+```
+
 [component-metadata:sl-animated-image]

docs/components/animation.md

@@ -4,7 +4,7 @@
 
 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">
@@ -19,12 +19,39 @@ To animate an element, wrap it in `<sl-animation>` and set an animation `name`.
     display: inline-block;
     width: 100px;
     height: 100px;
-    background-color: rgb(var(--sl-color-primary-600));
+    background-color: var(--sl-color-primary-600);
     margin: 1.5rem;
   }
 </style>
 ```
 
+```jsx react
+import { SlAnimation } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .animation-overview .box {
+    display: inline-block;
+    width: 100px;
+    height: 100px;
+    background-color: var(--sl-color-primary-600);
+    margin: 1.5rem;
+  }
+`;
+
+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>
+    </div>
+
+    <style>{css}</style> 
+  </>
+);
+```
+
 ?> The animation will only be applied to the first child element found in `<sl-animation>`.
 
 ## Examples
@@ -42,7 +69,7 @@ This example demonstrates all of the baked-in animations and easings. Animations
   <div class="controls">
     <sl-select label="Animation" value="bounce"></sl-select>
     <sl-select label="Easing" value="linear"></sl-select>
-    <sl-range min="0" max="2" step=".5" value="1"></sl-range>
+    <sl-input label="Playback Rate" type="number" min="0" max="2" step=".25" value="1"></sl-input>
   </div>
 </div>
 
@@ -53,7 +80,7 @@ This example demonstrates all of the baked-in animations and easings. Animations
   const animation = container.querySelector('sl-animation');
   const animationName = container.querySelector('.controls sl-select:nth-child(1)');
   const easingName = container.querySelector('.controls sl-select:nth-child(2)');
-  const playbackRate = container.querySelector('sl-range');
+  const playbackRate = container.querySelector('sl-input[type="number"]');
   const animations = getAnimationNames();
   const easings = getEasingNames();
 
@@ -75,15 +102,14 @@ This example demonstrates all of the baked-in animations and easings. Animations
 
   animationName.addEventListener('sl-change', () => animation.name = animationName.value);
   easingName.addEventListener('sl-change', () => animation.easing = easingName.value);
-  playbackRate.addEventListener('sl-change', () => animation.playbackRate = playbackRate.value);
-  playbackRate.tooltipFormatter = val => `Playback Rate = ${val}`;
+  playbackRate.addEventListener('sl-input', () => animation.playbackRate = playbackRate.value);
 </script>
 
 <style>
   .animation-sandbox .box {
     width: 100px;
     height: 100px;
-    background-color: rgb(var(--sl-color-primary-600));
+    background-color: var(--sl-color-primary-600);
   }
 
   .animation-sandbox .controls {
@@ -129,11 +155,68 @@ Use an [Intersection Observer](https://developer.mozilla.org/en-US/docs/Web/API/
     display: inline-block;
     width: 100px;
     height: 100px;
-    background-color: rgb(var(--sl-color-primary-600));
+    background-color: var(--sl-color-primary-600);
   }  
 </style>
 ```
 
+```jsx react
+import { useEffect, useRef, useState } from 'react';
+import { SlAnimation } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .animation-scroll {
+    height: calc(100vh + 100px);
+  }
+
+  .animation-scroll .box {
+    display: inline-block;
+    width: 100px;
+    height: 100px;
+    background-color: var(--sl-color-primary-600);
+  }
+`;
+
+const App = () => {
+  const animation = useRef(null);
+  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;
+        }
+      }
+    );
+
+    if (box.current) {
+      observer.observe(box.current);
+    }
+  }, [box]);
+
+  return (
+    <>
+      <div class="animation-scroll">
+        <SlAnimation
+          ref={animation}
+          name="jackInTheBox" 
+          duration={2000} 
+          iterations={1}
+        >
+          <div ref={box} class="box" />
+        </SlAnimation>
+      </div>
+
+      <style>{css}</style> 
+    </>
+  );
+};
+```
+
 ### Custom Keyframe Formats
 
 Supply your own [keyframe formats](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API/Keyframe_Formats) to build custom animations.
@@ -169,11 +252,55 @@ Supply your own [keyframe formats](https://developer.mozilla.org/en-US/docs/Web/
   .animation-keyframes .box {
     width: 100px;
     height: 100px;
-    background-color: rgb(var(--sl-color-primary-600));
+    background-color: var(--sl-color-primary-600);
   }
 </style>
 ```
 
+```jsx react
+import { SlAnimation } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .animation-keyframes .box {
+    width: 100px;
+    height: 100px;
+    background-color: var(--sl-color-primary-600);
+  }
+`;
+
+const App = () => (
+  <>
+    <div class="animation-keyframes">
+      <SlAnimation 
+        easing="ease-in-out" 
+        duration={2000} 
+        play
+        keyframes={[
+          {
+            offset: 0,
+            easing: 'cubic-bezier(0.250, 0.460, 0.450, 0.940)',
+            fillMode: 'both',
+            transformOrigin: 'center center',
+            transform: 'rotate(0)'
+          },
+          {
+            offset: 1,
+            easing: 'cubic-bezier(0.250, 0.460, 0.450, 0.940)',
+            fillMode: 'both',
+            transformOrigin: 'center center',
+            transform: 'rotate(90deg)'
+          }
+        ]}
+      >
+        <div class="box" />
+      </SlAnimation>
+    </div>
+
+    <style>{css}</style> 
+  </>
+);
+```
+
 ### Playing Animations on Demand
 
 Animations won't play until you apply the `play` attribute. You can omit it initially, then apply it on demand such as after a user interaction. In this example, the button will animate once every time the button is clicked.
@@ -181,7 +308,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>
 
@@ -196,4 +323,29 @@ Animations won't play until you apply the `play` attribute. You can omit it init
 </script>
 ```
 
+```jsx react
+import { useState } from 'react';
+import { SlAnimation, SlButton } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [play, setPlay] = useState(false);
+
+  return (
+    <div class="animation-form">
+      <SlAnimation 
+        name="rubberBand" 
+        duration={1000} 
+        iterations={1} 
+        play={play}
+        onSlFinish={() => setPlay(false)}
+      >
+        <SlButton variant="primary" onClick={() => setPlay(true)}>
+          Click me
+        </SlButton>
+      </SlAnimation>
+    </div>
+  );
+};
+```
+
 [component-metadata:sl-animation]

docs/components/avatar.md

@@ -4,8 +4,18 @@
 
 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.
+
 ```html preview
-<sl-avatar></sl-avatar>
+<sl-avatar label="User avatar"></sl-avatar>
+```
+
+```jsx react
+import { SlAvatar } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlAvatar label="User avatar" />
+);
 ```
 
 ## Examples
@@ -17,16 +27,35 @@ To use an image for the avatar, set the `image` and `alt` attributes. This will
 ```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="Gray tabby kitten looking down"
+  label="Avatar of a gray tabby kitten looking down"
 ></sl-avatar>
 ```
 
+```jsx react
+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"
+    label="Avatar of a gray tabby kitten looking down"
+  />
+);
+```
+
 ### Initials
 
 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"></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" label="Avatar with initials: SL" />
+);
 ```
 
 ### Custom Icons
@@ -34,31 +63,60 @@ When you don't have an image to use, you can set the `initials` attribute to sho
 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>
+<sl-avatar label="Avatar with an image icon">
   <sl-icon slot="icon" name="image"></sl-icon>
 </sl-avatar>
 
-<sl-avatar>
+<sl-avatar label="Avatar with an archive icon">
   <sl-icon slot="icon" name="archive"></sl-icon>
 </sl-avatar>
 
-<sl-avatar>
+<sl-avatar label="Avatar with a briefcase icon">
   <sl-icon slot="icon" name="briefcase"></sl-icon>
 </sl-avatar>
 ```
 
+```jsx react
+import { SlAvatar, SlIcon } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlAvatar label="Avatar with an image icon">
+      <SlIcon slot="icon" name="image" />
+    </SlAvatar>
+
+    <SlAvatar label="Avatar with an archive icon">
+      <SlIcon slot="icon" name="archive" />
+    </SlAvatar>
+
+    <SlAvatar label="Avatar with a briefcase icon">
+      <SlIcon slot="icon" name="briefcase" />
+    </SlAvatar>
+  </>
+);
+```
+
 ### Shapes
 
 Avatars can be shaped using the `shape` attribute.
 
 ```html preview
-<sl-avatar shape="square"></sl-avatar>
-
-<sl-avatar shape="rounded"></sl-avatar>
-
-<sl-avatar shape="circle"></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
+import { SlAvatar, SlIcon } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlAvatar shape="square" label="Square avatar" />
+    <SlAvatar shape="rounded" label="Rounded avatar" />
+    <SlAvatar shape="circle" label="Circle avatar" />
+  </>
+);
+```
 
 ### Avatar Groups
 
@@ -66,10 +124,25 @@ You can group avatars with a few lines of CSS.
 
 ```html preview
 <div class="avatar-group">
-  <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"></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"></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"></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"></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"
+    label="Avatar 1 of 4"
+  ></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"
+    label="Avatar 2 of 4"
+  ></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"
+    label="Avatar 3 of 4"
+  ></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"
+    label="Avatar 4 of 4"
+  ></sl-avatar>
 </div>
 
 <style>
@@ -78,9 +151,51 @@ You can group avatars with a few lines of CSS.
   }
 
   .avatar-group sl-avatar::part(base) {
-    border: solid 2px rgb(var(--sl-color-neutral-0));
+    border: solid 2px var(--sl-color-neutral-0);
   }
 </style>
 ```
 
+```jsx react
+import { SlAvatar, SlIcon } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .avatar-group sl-avatar:not(:first-of-type) {
+    margin-left: -1rem;
+  }
+
+  .avatar-group sl-avatar::part(base) {
+    border: solid 2px var(--sl-color-neutral-0);
+  }
+`;
+
+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" 
+        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" 
+        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" 
+        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" 
+        label="Avatar 4 of 4" 
+      />
+    </div>
+
+    <style>{css}</style>    
+  </>
+);
+```
+
 [component-metadata:sl-avatar]

docs/components/badge.md

@@ -8,18 +8,40 @@ Badges are used to draw attention and display statuses or counts.
 <sl-badge>Badge</sl-badge>
 ```
 
+```jsx react
+import { SlBadge } from '@shoelace-style/shoelace/dist/react';
+
+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
+import { SlBadge } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <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>  
+  </>
+);
 ```
 
 ### Pill Badges
@@ -27,11 +49,25 @@ Set the `type` attribute to change the badge's type.
 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
+import { SlBadge } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlBadge variant="primary" pill>Primary</SlBadge>
+    <SlBadge variant="success" pill>Success</SlBadge>
+    <SlBadge variant="neutral" pill>Neutral</SlBadge>
+    <SlBadge variant="warning" pill>Warning</SlBadge>
+    <SlBadge variant="danger" pill>Danger</SlBadge>  
+  </>
+);
 ```
 
 ### Pulsating Badges
@@ -40,11 +76,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>
@@ -54,6 +90,30 @@ Use the `pulse` attribute to draw attention to the badge with a subtle animation
 </style>
 ```
 
+```jsx react
+import { SlBadge } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .badge-pulse sl-badge:not(:last-of-type) {
+    margin-right: 1rem;
+  }
+`;
+
+const App = () => (
+  <>
+    <div className="badge-pulse">
+      <SlBadge variant="primary" pill pulse>1</SlBadge>
+      <SlBadge variant="success" pill pulse>1</SlBadge>
+      <SlBadge variant="neutral" pill pulse>1</SlBadge>
+      <SlBadge variant="warning" pill pulse>1</SlBadge>
+      <SlBadge variant="danger" pill pulse>1</SlBadge>
+    </div>
+
+    <style>{css}</style>
+  </>
+);
+```
+
 ### With Buttons
 
 One of the most common use cases for badges is attaching them to buttons. To make this easier, badges will be automatically positioned at the top-right when they're a child of a button.
@@ -66,25 +126,66 @@ One of the most common use cases for badges is attaching them to buttons. To mak
 
 <sl-button style="margin-left: 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;">
   Errors
-  <sl-badge type="danger" pill>6</sl-badge>
+  <sl-badge variant="danger" pill>6</sl-badge>
 </sl-button>
 ```
 
+```jsx react
+import { SlBadge, SlButton } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlButton>
+      Requests
+      <SlBadge pill>30</SlBadge>
+    </SlButton>
+
+    <SlButton style={{ marginLeft: '1rem' }}>
+      Warnings
+      <SlBadge variant="warning" pill>8</SlBadge>
+    </SlButton>
+
+    <SlButton style={{ marginLeft: '1rem' }}>
+      Errors
+      <SlBadge variant="danger" pill>6</SlBadge>
+    </SlButton>
+  </>
+);
+```
+
 ### With Menu Items
 
 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 rgb(var(--sl-panel-border-color)); border-radius: var(--sl-border-radius-medium);">
+<sl-menu style="max-width: 240px; border: solid 1px var(--sl-panel-border-color); border-radius: var(--sl-border-radius-medium);">
   <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>
 ```
 
+```jsx react
+import { SlBadge, SlButton, SlMenu, SlMenuItem, SlMenuLabel } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlMenu 
+    style={{
+      maxWidth: '240px',
+      border: 'solid 1px var(--sl-panel-border-color)',
+      borderRadius: 'var(--sl-border-radius-medium)'
+    }}
+  >
+    <SlMenuLabel>Messages</SlMenuLabel>
+    <SlMenuItem>Comments <SlBadge slot="suffix" variant="neutral" pill>4</SlBadge></SlMenuItem>
+    <SlMenuItem>Replies <SlBadge slot="suffix" variant="neutral" pill>12</SlBadge></SlMenuItem>
+  </SlMenu>
+);
+```
+
 [component-metadata:sl-badge]

docs/components/breadcrumb-item.md

@@ -15,6 +15,21 @@ Breadcrumb Items are used inside [breadcrumbs](/components/breadcrumb) to repres
 </sl-breadcrumb>
 ```
 
+```jsx react
+import { SlBreadcrumb, SlBreadcrumbItem, SlIcon } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlBreadcrumb>
+    <SlBreadcrumbItem>
+      <SlIcon slot="prefix" name="house"></SlIcon>
+      Home
+    </SlBreadcrumbItem>
+    <SlBreadcrumbItem>Clothing</SlBreadcrumbItem>
+    <SlBreadcrumbItem>Shirts</SlBreadcrumbItem>
+  </SlBreadcrumb>
+);
+```
+
 ?> Additional demonstrations can be found in the [breadcrumb examples](/components/breadcrumb).
 
 [component-metadata:sl-breadcrumb-item]

docs/components/breadcrumb.md

@@ -15,6 +15,19 @@ Breadcrumbs are usually placed before a page's main content with the current pag
 </sl-breadcrumb>
 ```
 
+```jsx react
+import { SlBreadcrumb, SlBreadcrumbItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlBreadcrumb>
+    <SlBreadcrumbItem>Catalog</SlBreadcrumbItem>
+    <SlBreadcrumbItem>Clothing</SlBreadcrumbItem>
+    <SlBreadcrumbItem>Women's</SlBreadcrumbItem>
+    <SlBreadcrumbItem>Shirts &amp; Tops</SlBreadcrumbItem>
+  </SlBreadcrumb>
+);
+```
+
 ## Examples
 
 ### Breadcrumb Links
@@ -43,6 +56,30 @@ For websites, you'll probably want to use links instead. You can make any breadc
 </sl-breadcrumb>
 ```
 
+```jsx react
+import { SlBreadcrumb, SlBreadcrumbItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlBreadcrumb>
+    <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/digital">
+      Digital Media
+    </SlBreadcrumbItem>
+
+    <SlBreadcrumbItem href="https://example.com/home/services/digital/web-design">
+      Web Design
+    </SlBreadcrumbItem>
+  </SlBreadcrumb>
+);
+```
+
 ### Custom Separators
 
 Use the `separator` slot to change the separator that goes between breadcrumb items. Icons work well, but you can also use text or an image.
@@ -74,6 +111,40 @@ Use the `separator` slot to change the separator that goes between breadcrumb it
 </sl-breadcrumb>
 ```
 
+```jsx react
+import '@shoelace-style/shoelace/dist/components/icon/icon.js';
+import { SlBreadcrumb, SlBreadcrumbItem } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlBreadcrumb>
+      <sl-icon name="dot" slot="separator" />
+      <SlBreadcrumbItem>First</SlBreadcrumbItem>
+      <SlBreadcrumbItem>Second</SlBreadcrumbItem>
+      <SlBreadcrumbItem>Third</SlBreadcrumbItem> 
+    </SlBreadcrumb>
+
+    <br />
+
+    <SlBreadcrumb>
+      <sl-icon name="arrow-right" slot="separator" />
+      <SlBreadcrumbItem>First</SlBreadcrumbItem>
+      <SlBreadcrumbItem>Second</SlBreadcrumbItem>
+      <SlBreadcrumbItem>Third</SlBreadcrumbItem> 
+    </SlBreadcrumb>
+
+    <br />
+
+    <SlBreadcrumb>
+      <span slot="separator">/</span>
+      <SlBreadcrumbItem>First</SlBreadcrumbItem>
+      <SlBreadcrumbItem>Second</SlBreadcrumbItem>
+      <SlBreadcrumbItem>Third</SlBreadcrumbItem> 
+    </SlBreadcrumb>
+  </>
+);
+```
+
 ### Prefixes
 
 Use the `prefix` slot to add content before any breadcrumb item.
@@ -89,6 +160,21 @@ Use the `prefix` slot to add content before any breadcrumb item.
 </sl-breadcrumb>
 ```
 
+```jsx react
+import { SlBreadcrumb, SlBreadcrumbItem, SlIcon } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlBreadcrumb>
+    <SlBreadcrumbItem>
+      <SlIcon slot="prefix" name="house" />
+      Home
+    </SlBreadcrumbItem>
+    <SlBreadcrumbItem>Articles</SlBreadcrumbItem>
+    <SlBreadcrumbItem>Traveling</SlBreadcrumbItem>
+  </SlBreadcrumb>
+);
+```
+
 ### Suffixes
 
 Use the `suffix` slot to add content after any breadcrumb item.
@@ -104,6 +190,21 @@ Use the `suffix` slot to add content after any breadcrumb item.
 </sl-breadcrumb>
 ```
 
+```jsx react
+import { SlBreadcrumb, SlBreadcrumbItem, SlIcon } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlBreadcrumb>
+    <SlBreadcrumbItem>Documents</SlBreadcrumbItem>
+    <SlBreadcrumbItem>Policies</SlBreadcrumbItem>
+    <SlBreadcrumbItem>
+      Security
+      <SlIcon slot="suffix" name="shield-lock"></SlIcon>
+    </SlBreadcrumbItem>
+  </SlBreadcrumb>
+);
+```
+
 ### With Dropdowns
 
 Dropdown menus can be placed in a prefix or suffix slot to provide additional options.
@@ -129,4 +230,37 @@ Dropdown menus can be placed in a prefix or suffix slot to provide additional op
 </sl-breadcrumb>
 ```
 
+```jsx react
+import { 
+  SlBreadcrumb, 
+  SlBreadcrumbItem, 
+  SlButton,
+  SlDropdown,
+  SlIcon,
+  SlMenu,
+  SlMenuItem
+} from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlBreadcrumb>
+    <SlBreadcrumbItem>Homepage</SlBreadcrumbItem>
+    <SlBreadcrumbItem>Our Services</SlBreadcrumbItem>
+    <SlBreadcrumbItem>Digital Media</SlBreadcrumbItem>
+    <SlBreadcrumbItem>
+      Web Design
+      <SlDropdown slot="suffix">
+        <SlButton slot="trigger" size="small" circle>
+          <SlIcon label="More options" name="three-dots"></SlIcon>
+        </SlButton>
+        <SlMenu>
+          <SlMenuItem checked>Web Design</SlMenuItem>
+          <SlMenuItem>Web Development</SlMenuItem>
+          <SlMenuItem>Marketing</SlMenuItem>
+        </SlMenu>
+      </SlDropdown>    
+    </SlBreadcrumbItem>
+  </SlBreadcrumb>
+);
+```
+
 [component-metadata:sl-breadcrumb]

docs/components/button-group.md

@@ -12,6 +12,18 @@ Button groups can be used to group related buttons into sections.
 </sl-button-group>
 ```
 
+```jsx react
+import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlButtonGroup>
+    <SlButton>Left</SlButton>
+    <SlButton>Center</SlButton>
+    <SlButton>Right</SlButton>
+  </SlButtonGroup>
+);
+```
+
 ## Examples
 
 ### Button Sizes
@@ -42,50 +54,126 @@ All button sizes are supported, but avoid mixing sizes within the same button gr
 </sl-button-group>
 ```
 
+```jsx react
+import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlButtonGroup>
+      <SlButton size="small">Left</SlButton>
+      <SlButton size="small">Center</SlButton>
+      <SlButton size="small">Right</SlButton>
+    </SlButtonGroup>
+
+    <br /><br />
+
+    <SlButtonGroup>
+      <SlButton size="medium">Left</SlButton>
+      <SlButton size="medium">Center</SlButton>
+      <SlButton size="medium">Right</SlButton>
+    </SlButtonGroup>
+
+    <br /><br />
+
+    <SlButtonGroup>
+      <SlButton size="large">Left</SlButton>
+      <SlButton size="large">Center</SlButton>
+      <SlButton size="large">Right</SlButton>
+    </SlButtonGroup>
+  </>
+);
+```
+
 ### Theme Buttons
 
 Theme buttons are supported through the button's `type` 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 variant="primary">Left</sl-button>
+  <sl-button variant="primary">Center</sl-button>
+  <sl-button variant="primary">Right</sl-button>
 </sl-button-group>
 
 <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 variant="success">Left</sl-button>
+  <sl-button variant="success">Center</sl-button>
+  <sl-button variant="success">Right</sl-button>
 </sl-button-group>
 
 <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 variant="neutral">Left</sl-button>
+  <sl-button variant="neutral">Center</sl-button>
+  <sl-button variant="neutral">Right</sl-button>
 </sl-button-group>
 
 <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 variant="warning">Left</sl-button>
+  <sl-button variant="warning">Center</sl-button>
+  <sl-button variant="warning">Right</sl-button>
 </sl-button-group>
 
 <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 variant="danger">Left</sl-button>
+  <sl-button variant="danger">Center</sl-button>
+  <sl-button variant="danger">Right</sl-button>
 </sl-button-group>
 ```
 
+```jsx react
+import { SlButton, SlButtonGroup } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlButtonGroup>
+      <SlButton variant="primary">Left</SlButton>
+      <SlButton variant="primary">Center</SlButton>
+      <SlButton variant="primary">Right</SlButton>
+    </SlButtonGroup>
+
+    <br /><br />
+
+    <SlButtonGroup>
+      <SlButton variant="success">Left</SlButton>
+      <SlButton variant="success">Center</SlButton>
+      <SlButton variant="success">Right</SlButton>
+    </SlButtonGroup>
+
+    <br /><br />
+
+    <SlButtonGroup>
+      <SlButton variant="neutral">Left</SlButton>
+      <SlButton variant="neutral">Center</SlButton>
+      <SlButton variant="neutral">Right</SlButton>
+    </SlButtonGroup>
+
+    <br /><br />
+
+    <SlButtonGroup>
+      <SlButton variant="warning">Left</SlButton>
+      <SlButton variant="warning">Center</SlButton>
+      <SlButton variant="warning">Right</SlButton>
+    </SlButtonGroup>
+
+    <br /><br />
+
+    <SlButtonGroup>
+      <SlButton variant="danger">Left</SlButton>
+      <SlButton variant="danger">Center</SlButton>
+      <SlButton variant="danger">Right</SlButton>
+    </SlButtonGroup>
+  </>
+);
+```
+
 ### Pill Buttons
 
 Pill buttons are supported through the button's `pill` attribute.
@@ -114,6 +202,36 @@ Pill buttons are supported through the button's `pill` attribute.
 </sl-button-group>
 ```
 
+```jsx react
+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>
+
+    <br /><br />
+
+    <SlButtonGroup>
+      <SlButton size="medium" pill>Left</SlButton>
+      <SlButton size="medium" pill>Center</SlButton>
+      <SlButton size="medium" pill>Right</SlButton>
+    </SlButtonGroup>
+
+    <br /><br />
+
+    <SlButtonGroup>
+      <SlButton size="large" pill>Left</SlButton>
+      <SlButton size="large" pill>Center</SlButton>
+      <SlButton size="large" pill>Right</SlButton>
+    </SlButtonGroup>
+  </>
+);
+```
+
 ### Dropdowns in Button Groups
 
 Dropdowns can be placed inside button groups as long as the trigger is an `<sl-button>` element.
@@ -133,15 +251,40 @@ Dropdowns can be placed inside button groups as long as the trigger is an `<sl-b
 </sl-button-group>
 ```
 
+```jsx react
+import { 
+  SlButton, 
+  SlButtonGroup,
+  SlDropdown,
+  SlMenu,
+  SlMenuItem,
+} from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlButtonGroup> 
+    <SlButton>Button</SlButton>
+    <SlButton>Button</SlButton>
+    <SlDropdown>
+      <SlButton slot="trigger" caret>Dropdown</SlButton>
+      <SlMenu>
+        <SlMenuItem>Item 1</SlMenuItem>
+        <SlMenuItem>Item 2</SlMenuItem>
+        <SlMenuItem>Item 3</SlMenuItem>
+      </SlMenu>
+    </SlDropdown>
+  </SlButtonGroup>
+);
+```
+
 ### Split Buttons
 
 Create a split button using a button and a dropdown.
 
 ```html preview
 <sl-button-group> 
-  <sl-button type="primary">Save</sl-button>
+  <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-button>
     <sl-menu>
       <sl-menu-item>Save</sl-menu-item>
       <sl-menu-item>Save as&hellip;</sl-menu-item>
@@ -151,6 +294,30 @@ Create a split button using a button and a dropdown.
 </sl-button-group>
 ```
 
+```jsx react
+import { 
+  SlButton, 
+  SlButtonGroup,
+  SlDropdown,
+  SlMenu,
+  SlMenuItem,
+} from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlButtonGroup> 
+    <SlButton variant="primary">Save</SlButton>
+    <SlDropdown placement="bottom-end">
+      <SlButton slot="trigger" variant="primary" caret></SlButton>
+      <SlMenu>
+        <SlMenuItem>Save</SlMenuItem>
+        <SlMenuItem>Save as&hellip;</SlMenuItem>
+        <SlMenuItem>Save all</SlMenuItem>
+      </SlMenu>
+    </SlDropdown>
+  </SlButtonGroup>
+);
+```
+
 ### Tooltips in Button Groups
 
 Buttons can be wrapped in tooltips to provide more detail when the user interacts with them.
@@ -171,6 +338,32 @@ Buttons can be wrapped in tooltips to provide more detail when the user interact
 </sl-button-group>
 ```
 
+```jsx react
+import { 
+  SlButton, 
+  SlButtonGroup,
+  SlTooltip
+} from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlButtonGroup>
+      <SlTooltip content="I'm on the left">
+        <SlButton>Left</SlButton>
+      </SlTooltip>
+
+      <SlTooltip content="I'm in the middle">
+        <SlButton>Center</SlButton>
+      </SlTooltip>
+
+      <SlTooltip content="I'm on the right">
+        <SlButton>Right</SlButton>
+      </SlTooltip>
+    </SlButtonGroup>
+  </>
+);
+```
+
 ### Toolbar Example
 
 Create interactive toolbars with button groups.
@@ -218,4 +411,60 @@ Create interactive toolbars with button groups.
 </style>
 ```
 
+```jsx react
+import { 
+  SlButton, 
+  SlButtonGroup,
+  SlIcon,
+  SlTooltip
+} from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .button-group-toolbar sl-button-group:not(:last-of-type) {
+    margin-right: var(--sl-spacing-x-small);
+  }
+`;
+
+const App = () => (
+  <>
+    <div className="button-group-toolbar">
+      <SlButtonGroup label="History">
+        <SlTooltip content="Undo">
+          <SlButton><SlIcon name="arrow-counterclockwise"></SlIcon></SlButton>
+        </SlTooltip>
+        <SlTooltip content="Redo">
+          <SlButton><SlIcon name="arrow-clockwise"></SlIcon></SlButton>
+        </SlTooltip>
+      </SlButtonGroup>
+
+      <SlButtonGroup label="Formatting">
+        <SlTooltip content="Bold">
+          <SlButton><SlIcon name="type-bold"></SlIcon></SlButton>
+        </SlTooltip>
+        <SlTooltip content="Italic">
+          <SlButton><SlIcon name="type-italic"></SlIcon></SlButton>
+        </SlTooltip>
+        <SlTooltip content="Underline">
+          <SlButton><SlIcon name="type-underline"></SlIcon></SlButton>
+        </SlTooltip>
+      </SlButtonGroup>
+
+      <SlButtonGroup label="Alignment">
+        <SlTooltip content="Align Left">
+          <SlButton><SlIcon name="justify-left"></SlIcon></SlButton>
+        </SlTooltip>
+        <SlTooltip content="Align Center">
+          <SlButton><SlIcon name="justify"></SlIcon></SlButton>
+        </SlTooltip>
+        <SlTooltip content="Align Right">
+          <SlButton><SlIcon name="justify-right"></SlIcon></SlButton>
+        </SlTooltip>
+      </SlButtonGroup>
+    </div>
+
+    <style>{css}</style>
+  </>
+);
+```
+
 [component-metadata:sl-button-group]

docs/components/button.md

@@ -8,19 +8,42 @@ Buttons represent actions that are available to the user.
 <sl-button>Button</sl-button>
 ```
 
+```jsx react
+import { SlButton } from '@shoelace-style/shoelace/dist/react';
+
+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
+import { SlButton } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <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>  
+  </>
+);
 ```
 
 ### Sizes
@@ -33,17 +56,44 @@ Use the `size` attribute to change a button's size.
 <sl-button size="large">Large</sl-button>
 ```
 
+```jsx react
+import { SlButton } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlButton size="small">Small</SlButton>
+    <SlButton size="medium">Medium</SlButton>
+    <SlButton size="large">Large</SlButton>
+  </>
+);
+```
+
 ### Outline Buttons
 
 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
+import { SlButton } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlButton variant="default" outline>Default</SlButton>
+    <SlButton variant="primary" outline>Primary</SlButton>
+    <SlButton variant="success" outline>Success</SlButton>
+    <SlButton variant="neutral" outline>Neutral</SlButton>
+    <SlButton variant="warning" outline>Warning</SlButton>
+    <SlButton variant="danger" outline>Danger</SlButton>
+  </>
+);
 ```
 
 ### Pill Buttons
@@ -56,24 +106,60 @@ Use the `pill` attribute to give buttons rounded edges.
 <sl-button size="large" pill>Large</sl-button>
 ```
 
+```jsx react
+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>
+  </>
+);
+```
+
 ### Circle Buttons
 
 Use the `circle` attribute to create circular icon buttons.
 
 ```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"></sl-icon></sl-button>
+<sl-button variant="default" size="medium" circle><sl-icon name="gear"></sl-icon></sl-button>
+<sl-button variant="default" size="large" circle><sl-icon name="gear"></sl-icon></sl-button>
+```
+
+```jsx react
+import { SlButton, SlIcon } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlButton variant="default" size="small" circle><SlIcon name="gear" /></SlButton>
+    <SlButton variant="default" size="medium" circle><SlIcon name="gear" /></SlButton>
+    <SlButton variant="default" size="large" circle><SlIcon name="gear" /></SlButton>
+  </>
+);
 ```
 
 ### 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
+import { SlButton } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlButton variant="text" size="small">Text</SlButton>
+    <SlButton variant="text" size="medium">Text</SlButton>
+    <SlButton variant="text" size="large">Text</SlButton>
+  </>
+);
 ```
 
 ### Link Buttons
@@ -87,16 +173,41 @@ It's often helpful to have a button that works like a link. This is possible by
 <sl-button href="https://example.com/" disabled>Disabled</sl-button>
 ```
 
+```jsx react
+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>
+  </>
+);
+```
+
 ?> When a `target` is set, the link will receive `rel="noreferrer noopener"` for [security reasons](https://mathiasbynens.github.io/rel-noopener/).
 
 ### Setting a Custom Width
 
-As expected, buttons can be given a custom width by setting its `width`. This is useful for making buttons span the full width of their container on smaller screens.
+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
+import { SlButton } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlButton variant="default" size="small" style={{ width: '100%', marginBottom: '1rem' }}>Small</SlButton>
+    <SlButton variant="default" size="medium" style={{ width: '100%', marginBottom: '1rem' }}>Medium</SlButton>
+    <SlButton variant="default" size="large" style={{ width: '100%' }}>Large</SlButton>
+  </>
+);
 ```
 
 ### Prefix and Suffix Icons
@@ -104,17 +215,17 @@ As expected, buttons can be given a custom width by setting its `width`. This is
 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
@@ -122,17 +233,17 @@ Use the `prefix` and `suffix` slots to add icons.
 
 <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
@@ -140,23 +251,83 @@ Use the `prefix` and `suffix` slots to add icons.
 
 <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
 </sl-button>
 ```
 
+```jsx react
+import { SlButton, SlIcon } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlButton variant="default" size="small">
+      <SlIcon slot="prefix" name="gear"></SlIcon>
+      Settings
+    </SlButton>
+
+    <SlButton variant="default" size="small">
+      <SlIcon slot="suffix" name="arrow-counterclockwise"></SlIcon>
+      Refresh
+    </SlButton>
+
+    <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/ >
+
+    <SlButton variant="default">
+      <SlIcon slot="prefix" name="gear"></SlIcon>
+      Settings
+    </SlButton>
+
+    <SlButton variant="default">
+      <SlIcon slot="suffix" name="arrow-counterclockwise"></SlIcon>
+      Refresh
+    </SlButton>
+
+    <SlButton variant="default">
+      <SlIcon slot="prefix" name="link-45deg"></SlIcon>
+      <SlIcon slot="suffix" name="box-arrow-up-right"></SlIcon>
+      Open
+    </SlButton>
+
+    <br /><br />
+
+    <SlButton variant="default" size="large">
+      <SlIcon slot="prefix" name="gear"></SlIcon>
+      Settings
+    </SlButton>
+
+    <SlButton variant="default" size="large">
+      <SlIcon slot="suffix" name="arrow-counterclockwise"></SlIcon>
+      Refresh
+    </SlButton>
+
+    <SlButton variant="default" size="large">
+      <SlIcon slot="prefix" name="link-45deg"></SlIcon>
+      <SlIcon slot="suffix" name="box-arrow-up-right"></SlIcon>
+      Open
+    </SlButton>
+  </>
+);
+```
+
 ### Caret
 
 Use the `caret` attribute to add a dropdown indicator when a button will trigger a dropdown, menu, or popover.
@@ -167,17 +338,44 @@ Use the `caret` attribute to add a dropdown indicator when a button will trigger
 <sl-button size="large" caret>Large</sl-button>
 ```
 
+```jsx react
+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>
+  </>
+);
+```
+
 ### Loading
 
 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
+import { SlButton } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlButton variant="default" loading>Default</SlButton>
+    <SlButton variant="primary" loading>Primary</SlButton>
+    <SlButton variant="success" loading>Success</SlButton>
+    <SlButton variant="neutral" loading>Neutral</SlButton>
+    <SlButton variant="warning" loading>Warning</SlButton>
+    <SlButton variant="danger" loading>Danger</SlButton>
+  </>
+);
 ```
 
 ### Disabled
@@ -185,17 +383,32 @@ Use the `loading` attribute to make a button busy. The width will remain the sam
 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
+import { SlButton } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlButton variant="default" disabled>Default</SlButton>
+    <SlButton variant="primary" disabled>Primary</SlButton>
+    <SlButton variant="success" disabled>Success</SlButton>
+    <SlButton variant="neutral" disabled>Neutral</SlButton>
+    <SlButton variant="warning" disabled>Warning</SlButton>
+    <SlButton variant="danger" disabled>Danger</SlButton>
+  </>
+);
 ```
 
 ### 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>

docs/components/card.md

@@ -17,7 +17,7 @@ Cards can be used to group related subjects in a container.
   <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>
@@ -28,7 +28,7 @@ Cards can be used to group related subjects in a container.
   }
 
   .card-overview small {
-    color: rgb(var(--sl-color-neutral-500));
+    color: var(--sl-color-neutral-500);
   }
 
   .card-overview [slot="footer"] {
@@ -39,6 +39,53 @@ Cards can be used to group related subjects in a container.
 </style>
 ```
 
+```jsx react
+import { 
+  SlButton, 
+  SlCard, 
+  SlRating 
+} from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .card-overview {
+    max-width: 300px;
+  }
+
+  .card-overview small {
+    color: var(--sl-color-neutral-500);
+  }
+
+  .card-overview [slot="footer"] {
+    display: flex; 
+    justify-content: space-between; 
+    align-items: center;
+  }
+`;
+
+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" 
+        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 />
+      <small>6 weeks old</small>
+
+      <div slot="footer">
+        <SlButton variant="primary" pill>More Info</SlButton>
+        <SlRating></SlRating>
+      </div>
+    </SlCard>
+
+    <style>{css}</style>
+  </>
+);
+```
+
 ## Examples
 
 ## Basic Card
@@ -57,6 +104,26 @@ Basic cards aren't very exciting, but they can display any content you want them
 </style>
 ```
 
+```jsx react
+import { SlCard } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .card-basic {
+    max-width: 300px;
+  }
+`;
+
+const App = () => (
+  <>
+    <SlCard className="card-basic">
+      This is just a basic card. No image, no header, and no footer. Just your content.
+    </SlCard>
+
+    <style>{css}</style>
+  </>
+);
+```
+
 ## Card with Header
 
 Headers can be used to display titles and more.
@@ -73,26 +140,66 @@ Headers can be used to display titles and more.
 </sl-card>
 
 <style>
-.card-header {
-  max-width: 300px;
-}
+  .card-header {
+    max-width: 300px;
+  }
 
-.card-header [slot="header"] {
-  display: flex; 
-  align-items: center; 
-  justify-content: space-between;
-}
+  .card-header [slot="header"] {
+    display: flex; 
+    align-items: center; 
+    justify-content: space-between;
+  }
 
-.card-header h3 {
-  margin: 0;
-}
+  .card-header h3 {
+    margin: 0;
+  }
 
-.card-header sl-icon-button {
-  font-size: var(--sl-font-size-medium);
-}
+  .card-header sl-icon-button {
+    font-size: var(--sl-font-size-medium);
+  }
 </style>
 ```
 
+```jsx react
+import { SlCard, SlIconButton } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .card-header {
+    max-width: 300px;
+  }
+
+  .card-header [slot="header"] {
+    display: flex; 
+    align-items: center; 
+    justify-content: space-between;
+  }
+
+  .card-header h3 {
+    margin: 0;
+  }
+
+  .card-header sl-icon-button {
+    font-size: var(--sl-font-size-medium);
+  }
+`;
+
+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>
+
+    <style>{css}</style>
+  </>
+);
+```
+
 ## Card with Footer
 
 Footers can be used to display actions, summaries, or other relevant content.
@@ -103,7 +210,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 slot="footer" variant="primary">Preview</sl-button>
   </div>
 </sl-card>
 
@@ -120,6 +227,41 @@ Footers can be used to display actions, summaries, or other relevant content.
 </style>
 ```
 
+```jsx react
+import { 
+  SlButton, 
+  SlCard, 
+  SlRating 
+} from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .card-footer {
+    max-width: 300px;
+  }
+
+  .card-footer [slot="footer"] {
+    display: flex; 
+    justify-content: space-between; 
+    align-items: center;
+  }
+`;
+
+const App = () => (
+  <>
+    <SlCard className="card-footer">
+      This card has a footer. You can put all sorts of things in it!
+
+      <div slot="footer">
+        <SlRating></SlRating>
+        <SlButton slot="footer" variant="primary">Preview</SlButton>
+      </div>
+    </SlCard>
+
+    <style>{css}</style>
+  </>
+);
+```
+
 ## Images
 
 Cards accept an `image` slot. The image is displayed atop the card and stretches to fit.
@@ -141,4 +283,29 @@ Cards accept an `image` slot. The image is displayed atop the card and stretches
 </style>
 ```
 
+```jsx react
+import { SlCard } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .card-image {
+    max-width: 300px;
+  }
+`;
+
+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" 
+        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.
+    </SlCard>
+
+    <style>{css}</style>
+  </>
+);
+```
+
 [component-metadata:sl-card]

docs/components/checkbox.md

@@ -8,7 +8,15 @@ Checkboxes allow the user to toggle an option on or off.
 <sl-checkbox>Checkbox</sl-checkbox>
 ```
 
-?> This component doesn't work with standard forms. Use [`<sl-form>`](/components/form) instead.
+```jsx react
+import { SlCheckbox } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlCheckbox>Checkbox</SlCheckbox>
+);
+```
+
+?> 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
 
@@ -20,6 +28,14 @@ Use the `checked` attribute to activate the checkbox.
 <sl-checkbox checked>Checked</sl-checkbox>
 ```
 
+```jsx react
+import { SlCheckbox } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlCheckbox checked>Checked</SlCheckbox>
+);
+```
+
 ### Indeterminate
 
 Use the `indeterminate` attribute to make the checkbox indeterminate.
@@ -28,6 +44,14 @@ Use the `indeterminate` attribute to make the checkbox indeterminate.
 <sl-checkbox indeterminate>Indeterminate</sl-checkbox>
 ```
 
+```jsx react
+import { SlCheckbox } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlCheckbox indeterminate>Indeterminate</SlCheckbox>
+);
+```
+
 ### Disabled
 
 Use the `disabled` attribute to disable the checkbox.
@@ -36,4 +60,12 @@ Use the `disabled` attribute to disable the checkbox.
 <sl-checkbox disabled>Disabled</sl-checkbox>
 ```
 
+```jsx react
+import { SlCheckbox } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlCheckbox disabled>Disabled</SlCheckbox>
+);
+```
+
 [component-metadata:sl-checkbox]

docs/components/color-picker.md

@@ -8,6 +8,16 @@ Color pickers allow the user to select a color.
 <sl-color-picker></sl-color-picker>
 ```
 
+```jsx react
+import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlColorPicker />
+);
+```
+
+?> 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
@@ -18,6 +28,14 @@ Use the `opacity` attribute to enable the opacity slider. When this is enabled,
 <sl-color-picker opacity></sl-color-picker>
 ```
 
+```jsx react
+import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlColorPicker opacity />
+);
+```
+
 ### 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.
@@ -30,6 +48,18 @@ To prevent users from toggling the format themselves, add the `no-format-toggle`
 <sl-color-picker format="hsl" value="hsl(290, 87%, 47%)"></sl-color-picker>
 ```
 
+```jsx react
+import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlColorPicker format="hex" value="#4a90e2" />
+    <SlColorPicker format="rgb" value="rgb(80, 227, 194)" />
+    <SlColorPicker format="hsl" value="hsl(290, 87%, 47%)" />
+  </>
+);
+```
+
 ### Sizes
 
 Use the `size` attribute to change the color picker's trigger size.
@@ -40,6 +70,17 @@ Use the `size` attribute to change the color picker's trigger size.
 <sl-color-picker size="large"></sl-color-picker>
 ```
 
+```jsx react
+import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlColorPicker size="small" />
+    <SlColorPicker size="medium" />
+    <SlColorPicker size="large" />
+  </>
+);
+```
 
 ### Inline
 
@@ -49,4 +90,12 @@ The color picker can be rendered inline instead of in a dropdown using the `inli
 <sl-color-picker inline></sl-color-picker>
 ```
 
+```jsx react
+import { SlColorPicker } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlColorPicker inline />
+);
+```
+
 [component-metadata:sl-color-picker]

docs/components/context-menu.md

@@ -1,140 +0,0 @@
-# Context Menu
-
-[component-header:sl-context-menu]
-
-Context menus offer additional options through a menu that opens at the pointer's location, usually activated by a right-click.
-
-Context menus are designed to work with [menus](/components/menu) and [menu items](/components/menu-item). The menu must include `slot="menu"`. Other content you provide will be part of the context menu's target area.
-
-```html preview
-<sl-context-menu>
-  <div style="height: 200px; background: rgb(var(--sl-color-neutral-100)); display: flex; align-items: center; justify-content: center; padding: 1rem;">
-    Right-click to activate the context menu
-  </div>
-
-  <sl-menu slot="menu">
-    <sl-menu-item value="undo">Undo</sl-menu-item>
-    <sl-menu-item value="redo">Redo</sl-menu-item>
-    <sl-divider></sl-divider>
-    <sl-menu-item value="cut">Cut</sl-menu-item>
-    <sl-menu-item value="copy">Copy</sl-menu-item>
-    <sl-menu-item value="paste">Paste</sl-menu-item>
-    <sl-menu-item value="delete">Delete</sl-menu-item>
-  </sl-menu>
-</sl-context-menu>
-```
-
-## Examples
-
-### Handling Selections
-
-The [menu component](/components/menu) emits an `sl-select` event when a menu item is selected. You can use this to handle selections. The selected item will be available in `event.detail.item`.
-
-```html preview
-<div class="context-menu-selections">
-  <sl-context-menu>
-    <div style="height: 200px; background: rgb(var(--sl-color-neutral-100)); display: flex; align-items: center; justify-content: center; padding: 1rem;">
-      Right-click to activate the context menu
-    </div>
-
-    <sl-menu slot="menu">
-      <sl-menu-item value="cut">Cut</sl-menu-item>
-      <sl-menu-item value="copy">Copy</sl-menu-item>
-      <sl-menu-item value="paste">Paste</sl-menu-item>
-    </sl-menu>
-  </sl-context-menu>
-</div>
-
-<script>
-  const container = document.querySelector('.context-menu-selections');
-  const menu = container.querySelector('sl-menu');
-  const result = container.querySelector('.result');
-
-  menu.addEventListener('sl-select', event => {
-    console.log(`You selected: ${event.detail.item.value}`);
-  });
-</script>
-```
-
-### Inline
-
-The context menu uses `display: contents`, so it will assume the shape of the content you slot in.
-
-```html preview
-<sl-context-menu>
-  <span style="background: rgb(var(--sl-color-neutral-100)); padding: .5rem 1rem;">
-    Right-click here
-  </span>
-
-  <sl-menu slot="menu">
-    <sl-menu-item value="cut">Cut</sl-menu-item>
-    <sl-menu-item value="copy">Copy</sl-menu-item>
-    <sl-menu-item value="paste">Paste</sl-menu-item>
-  </sl-menu>
-</sl-context-menu>
-```
-
-### Placement
-
-The preferred placement of the context menu can be set with the `placement` attribute. Note that the actual position may vary to ensure the menu remains in the viewport.
-
-```html preview
-<sl-context-menu placement="top-end">
-  <div style="height: 200px; background: rgb(var(--sl-color-neutral-100)); display: flex; align-items: center; justify-content: center; padding: 1rem;">
-    Right-click to activate the context menu
-  </div>
-
-  <sl-menu slot="menu">
-    <sl-menu-item value="undo">Undo</sl-menu-item>
-    <sl-menu-item value="redo">Redo</sl-menu-item>
-    <sl-divider></sl-divider>
-    <sl-menu-item value="cut">Cut</sl-menu-item>
-    <sl-menu-item value="copy">Copy</sl-menu-item>
-    <sl-menu-item value="paste">Paste</sl-menu-item>
-    <sl-menu-item value="delete">Delete</sl-menu-item>
-  </sl-menu>
-</sl-context-menu>
-```
-
-### Detecting the Target Item
-
-A single context menu can wrap a number of items. To detect the item that activated the context menu...
-
-TODO
-
-```html preview
-<div class="context-menu-detecting">
-  <sl-context-menu>
-    <ul>
-      <li>Item 1</li>
-      <li>Item 2</li>
-      <li>Item 3</li>
-      <li>Item 4</li>
-      <li>Item 5</li>
-    </ul>
-
-    <sl-menu slot="menu">
-      <sl-menu-item value="cut">Cut</sl-menu-item>
-      <sl-menu-item value="copy">Copy</sl-menu-item>
-      <sl-menu-item value="paste">Paste</sl-menu-item>
-    </sl-menu>
-  </sl-context-menu>
-</div>
-
-<style>
-  .context-menu-detecting ul {
-    max-width: 300px;
-    list-style: none;
-    padding: 0;
-    margin: 0;
-  }
-  
-  .context-menu-detecting li {
-    background: rgb(var(--sl-color-neutral-100));
-    padding: .5rem 1rem;
-    margin: 0 0 2px 0;
-  }
-</style>
-```
-
-[component-metadata:sl-context-menu]

docs/components/details.md

@@ -1,3 +1,5 @@
+<!-- cspell:dictionaries lorem-ipsum -->
+
 # Details
 
 [component-header:sl-details]
@@ -11,6 +13,17 @@ Details show a brief summary and expand to show additional content.
 </sl-details>
 ```
 
+```jsx react
+import { SlDetails } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlDetails summary="Toggle Me">
+    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>
+);
+```
+
 ## Examples
 
 ### Disabled
@@ -24,6 +37,17 @@ Use the `disable` attribute to prevent the details from expanding.
 </sl-details>
 ```
 
+```jsx react
+import { SlDetails } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlDetails summary="Disabled" disabled>
+    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>
+);
+```
+
 ### 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,3 +1,5 @@
+<!-- cspell:dictionaries lorem-ipsum -->
+
 # Dialog
 
 [component-header:sl-dialog]
@@ -7,7 +9,7 @@ Dialogs, sometimes called "modals", appear above the page and require the user's
 ```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>
@@ -22,6 +24,28 @@ Dialogs, sometimes called "modals", appear above the page and require the user's
 </script>
 ```
 
+```jsx react
+import { useState } from 'react';
+import { SlButton, SlDialog } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <SlDialog label="Dialog" open={open} onSlAfterHide={() => setOpen(false)}>
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+        <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
+          Close
+        </SlButton>
+      </SlDialog>
+
+      <SlButton onClick={() => setOpen(true)}>Open Dialog</SlButton>
+    </>
+  );
+};
+```
+
 ## UX Tips
 
 - Use a dialog when you immediately require the user's attention, e.g. confirming a destructive action.
@@ -37,7 +61,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>
@@ -52,16 +76,38 @@ Use the `--width` custom property to set the dialog's width.
 </script>
 ```
 
+```jsx react
+import { useState } from 'react';
+import { SlButton, SlDialog } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <SlDialog label="Dialog" open={open} style={{ '--width': '50vw' }} onSlAfterHide={() => setOpen(false)}>
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+        <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
+          Close
+        </SlButton>
+      </SlDialog>
+
+      <SlButton onClick={() => setOpen(true)}>Open Dialog</SlButton>
+    </>
+  );
+};
+```
+
 ### Scrolling
 
 By design, a dialog's height will never exceed that of the viewport. As such, dialogs will not scroll with the page ensuring the header and footer are always accessible to the user.
 
 ```html preview
 <sl-dialog label="Dialog" class="dialog-scrolling">
-  <div style="height: 150vh; border: dashed 2px rgb(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>
-  <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>
@@ -76,16 +122,49 @@ By design, a dialog's height will never exceed that of the viewport. As such, di
 </script>
 ```
 
+```jsx react
+import { useState } from 'react';
+import { SlButton, SlDialog } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <SlDialog label="Dialog" open={open} onSlAfterHide={() => setOpen(false)}>
+        <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" variant="primary" onClick={() => setOpen(false)}>
+          Close
+        </SlButton>
+      </SlDialog>
+
+      <SlButton onClick={() => setOpen(true)}>Open Dialog</SlButton>
+    </>
+  );
+};
+```
+
 ### Preventing the Dialog from Closing
 
 By default, dialogs will close when the user clicks the close button, clicks the overlay, or presses the <kbd>Escape</kbd> key. In most cases, the default behavior is the best behavior in terms of UX. However, there are situations where this may be undesirable, such as when data loss will occur.
 
 To keep the dialog open in such cases, you can cancel the `sl-request-close` event. When canceled, the dialog will remain open and pulse briefly to draw the user's attention to it.
 
+You can use `event.detail.source` to determine what triggered the request to close. This example prevents the dialog from closing when the overlay is clicked, but allows the close button or <kbd>Escape</kbd> to dismiss it.
+
 ```html preview
 <sl-dialog label="Dialog" class="dialog-deny-close">
-  This dialog will not close unless you use the button below.
-  <sl-button slot="footer" 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>
@@ -93,23 +172,62 @@ 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>
 ```
 
+```jsx react
+import { useState } from 'react';
+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={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>
+
+      <SlButton onClick={() => setOpen(true)}>Open Dialog</SlButton>
+    </>
+  );
+};
+```
+
 ### Customizing Initial Focus
 
-By default, the dialog's panel will gain focus when opened. This allows the first 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 within the dialog. To set focus on a different element, listen for and cancel the `sl-initial-focus` event.
 
 ```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-button slot="footer" variant="primary">Close</sl-button>
 </sl-dialog>
 
 <sl-button>Open Dialog</sl-button>
@@ -130,4 +248,32 @@ By default, the dialog's panel will gain focus when opened. This allows the firs
 </script>
 ```
 
+```jsx react
+import { useRef, 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" variant="primary" onClick={() => setOpen(false)}>
+          Close
+        </SlButton>
+      </SlDialog>
+
+      <SlButton onClick={() => setOpen(true)}>Open Dialog</SlButton>
+    </>
+  );
+};
+```
+
 [component-metadata:sl-dialog]

docs/components/divider.md

@@ -8,6 +8,13 @@ Dividers are used to visually separate or group elements.
 <sl-divider></sl-divider>
 ```
 
+```jsx react
+import { SlDivider } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlDivider />
+);
+```
 ## Examples
 
 ### Width
@@ -18,6 +25,14 @@ Use the `--width` custom property to change the width of the divider.
 <sl-divider style="--width: 4px;"></sl-divider>
 ```
 
+```jsx react
+import { SlDivider } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlDivider style={{ '--width': '4px' }} />
+);
+```
+
 ### Color
 
 Use the `--color` custom property to change the color of the divider.
@@ -26,6 +41,14 @@ Use the `--color` custom property to change the color of the divider.
 <sl-divider style="--color: tomato;"></sl-divider>
 ```
 
+```jsx react
+import { SlDivider } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlDivider style={{ '--color': 'tomato' }} />
+);
+```
+
 ### Spacing
 
 Use the `--spacing` custom property to change the amount of space between the divider and it's neighboring elements.
@@ -38,6 +61,18 @@ Use the `--spacing` custom property to change the amount of space between the di
 </div>
 ```
 
+```jsx react
+import { SlDivider } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    Above
+    <SlDivider style={{ '--spacing': '2rem' }} />
+    Below
+  </>
+);
+```
+
 ### Vertical
 
 Add the `vertical` attribute to draw the divider in a vertical orientation. The divider will span the full height of its container. Vertical dividers work especially well inside of a flex container.
@@ -52,12 +87,32 @@ Add the `vertical` attribute to draw the divider in a vertical orientation. The
 </div>
 ```
 
+```jsx react
+import { SlDivider } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <div 
+    style={{ 
+      display: 'flex', 
+      alignItems: 'center', 
+      height: '2rem'
+    }}
+  >
+    First
+    <SlDivider vertical />
+    Middle
+    <SlDivider vertical />
+    Last
+  </div>
+);
+```
+
 ### Menu Dividers
 
 Use dividers in [menus](/components/menu) to visually group menu items.
 
 ```html preview
-<sl-menu style="max-width: 200px; border: solid 1px rgb(var(--sl-panel-border-color)); border-radius: var(--sl-border-radius-medium);">
+<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 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>
@@ -68,4 +123,30 @@ Use dividers in [menus](/components/menu) to visually group menu items.
 </sl-menu>
 ```
 
+```jsx 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)'
+    }}
+  >
+    <SlMenuItem value="1">Option 1</SlMenuItem>
+    <SlMenuItem value="2">Option 2</SlMenuItem>
+    <SlMenuItem value="3">Option 3</SlMenuItem>
+    <sl-divider />
+    <SlMenuItem value="4">Option 4</SlMenuItem>
+    <SlMenuItem value="5">Option 5</SlMenuItem>
+    <SlMenuItem value="6">Option 6</SlMenuItem>
+  </SlMenu>
+);
+```
+
 [component-metadata:sl-divider]

docs/components/drawer.md

@@ -1,3 +1,5 @@
+<!-- cspell:dictionaries lorem-ipsum -->
+
 # Drawer
 
 [component-header:sl-drawer]
@@ -7,7 +9,7 @@ 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,13 +17,35 @@ 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());
 </script>
 ```
 
+```jsx react
+import { useState } from 'react';
+import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <SlDrawer label="Drawer" open={open} onSlAfterHide={() => setOpen(false)}>
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+        <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
+          Close
+        </SlButton>
+      </SlDrawer>
+
+      <SlButton onClick={() => setOpen(true)}>Open Drawer</SlButton>
+    </>
+  );
+};
+```
+
 ## Examples
 
 ### Slide in From Start
@@ -31,7 +55,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>
@@ -39,13 +63,35 @@ 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());
 </script>
 ```
 
+```jsx react
+import { useState } from 'react';
+import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <SlDrawer label="Drawer" placement="start" open={open} onSlAfterHide={() => setOpen(false)}>
+        This drawer slides in from the start.
+        <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
+          Close
+        </SlButton>
+      </SlDrawer>
+
+      <SlButton onClick={() => setOpen(true)}>Open Drawer</SlButton>
+    </>
+  );
+};
+```
+
 ### Slide in From Top
 
 To make the drawer slide in from the top, set the `placement` attribute to `top`.
@@ -53,7 +99,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>
@@ -61,13 +107,35 @@ 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());
 </script>
 ```
 
+```jsx react
+import { useState } from 'react';
+import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <SlDrawer label="Drawer" placement="top" open={open} onSlAfterHide={() => setOpen(false)}>
+        This drawer slides in from the top.
+        <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
+          Close
+        </SlButton>
+      </SlDrawer>
+
+      <SlButton onClick={() => setOpen(true)}>Open Drawer</SlButton>
+    </>
+  );
+};
+```
+
 ### Slide in From Bottom
 
 To make the drawer slide in from the bottom, set the `placement` attribute to `bottom`.
@@ -75,7 +143,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>
@@ -83,26 +151,48 @@ 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());
 </script>
 ```
 
+```jsx react
+import { useState } from 'react';
+import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <SlDrawer label="Drawer" placement="bottom" open={open} onSlAfterHide={() => setOpen(false)}>
+        This drawer slides in from the bottom.
+        <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
+          Close
+        </SlButton>
+      </SlDrawer>
+
+      <SlButton onClick={() => setOpen(true)}>Open Drawer</SlButton>
+    </>
+  );
+};
+```
+
 ### 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.
 
 ```html preview
 <div
-  style="position: relative; border: solid 2px rgb(var(--sl-panel-border-color)); height: 300px; padding: 1rem; margin-bottom: 1rem;"
+  style="position: relative; border: solid 2px var(--sl-panel-border-color); height: 300px; padding: 1rem; margin-bottom: 1rem;"
 >
   The drawer will be contained to this box. This content won't shift or be affected in any way when the drawer opens.
 
   <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>
 
@@ -111,13 +201,47 @@ By default, the drawer slides out of its [containing block](https://developer.mo
 <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());
   closeButton.addEventListener('click', () => drawer.hide());
 </script>
 ```
 
+```jsx react
+import { useState } from 'react';
+import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <div
+        style={{
+          position: 'relative',
+          border: 'solid 2px var(--sl-panel-border-color)',
+          height: '300px',
+          padding: '1rem',
+          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.
+        <SlDrawer label="Drawer" contained open={open} onSlAfterHide={() => setOpen(false)} style={{ '--size': '50%' }}>
+          Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+          <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
+            Close
+          </SlButton>
+        </SlDrawer>
+      </div>
+
+      <SlButton onClick={() => setOpen(true)}>Open Drawer</SlButton>
+    </>
+  );
+};
+```
+
 ### Custom Size
 
 Use the `--size` custom property to set the drawer's size. This will be applied to the drawer's width or height depending on its `placement`.
@@ -125,7 +249,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>
@@ -133,23 +257,45 @@ 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());
 </script>
 ```
 
+```jsx react
+import { useState } from 'react';
+import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <SlDrawer label="Drawer" open={open} onSlAfterHide={() => setOpen(false)} style={{ '--size': '50vw' }}>
+        This drawer is always 50% of the viewport.
+        <SlButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
+          Close
+        </SlButton>
+      </SlDrawer>
+
+      <SlButton onClick={() => setOpen(true)}>Open Drawer</SlButton>
+    </>
+  );
+};
+```
+
 ### Scrolling
 
 By design, a drawer's height will never exceed 100% of its container. As such, drawers will not scroll with the page to ensure the header and footer are always accessible to the user.
 
 ```html preview
 <sl-drawer label="Drawer" class="drawer-scrolling">
-  <div style="height: 150vh; border: dashed 2px rgb(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>
-  <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>
@@ -157,24 +303,55 @@ 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());
 </script>
 ```
 
+```jsx react
+import { useState } from 'react';
+import { SlButton, SlDrawer } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <SlDrawer label="Drawer" open={open} onSlAfterHide={() => setOpen(false)}>
+        <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" variant="primary" onClick={() => setOpen(false)}>
+          Close
+        </SlButton>
+      </SlDrawer>
+
+      <SlButton onClick={() => setOpen(true)}>Open Drawer</SlButton>
+    </>
+  );
+};
+```
+
 ### Preventing the Drawer from Closing
 
 By default, drawers will close when the user clicks the close button, clicks the overlay, or presses the <kbd>Escape</kbd> key. In most cases, the default behavior is the best behavior in terms of UX. However, there are situations where this may be undesirable, such as when data loss will occur.
 
 To keep the drawer open in such cases, you can cancel the `sl-request-close` event. When canceled, the drawer will remain open and pulse briefly to draw the user's attention to it.
 
+You can use `event.detail.source` to determine what triggered the request to close. This example prevents the drawer from closing when the overlay is clicked, but allows the close button or <kbd>Escape</kbd> to dismiss it.
 
 ```html preview
 <sl-drawer label="Drawer" class="drawer-deny-close">
-  This dialog 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>
@@ -182,15 +359,55 @@ 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>
 ```
 
+```jsx react
+import { useState } from 'react';
+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={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>
+
+      <SlButton onClick={() => setOpen(true)}>Open Drawer</SlButton>
+    </>
+  );
+};
+```
+
 ### 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.
@@ -198,7 +415,7 @@ By default, the drawer's panel will gain focus when opened. This allows the firs
 ```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-button slot="footer" variant="primary">Close</sl-button>
 </sl-drawer>
 
 <sl-button>Open Drawer</sl-button>
@@ -207,7 +424,7 @@ 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());
@@ -215,8 +432,36 @@ By default, the drawer's panel will gain focus when opened. This allows the firs
   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';
+
+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" variant="primary" onClick={() => setOpen(false)}>
+          Close
+        </SlButton>
+      </SlDrawer>
+
+      <SlButton onClick={() => setOpen(true)}>Open Drawer</SlButton>
+    </>
+  );
+};
+```
+
 [component-metadata:sl-drawer]

docs/components/dropdown.md

@@ -31,6 +31,40 @@ Dropdowns are designed to work well with [menus](/components/menu) to provide a
 </sl-dropdown>
 ```
 
+```jsx react
+import { 
+  SlButton,
+  SlDivider,
+  SlDropdown,
+  SlIcon,
+  SlMenu,
+  SlMenuItem
+} from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlDropdown>
+    <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 disabled>Disabled</SlMenuItem>
+      <SlDivider />
+      <SlMenuItem>
+        Prefix
+        <SlIcon slot="prefix" name="gift" />
+      </SlMenuItem>
+      <SlMenuItem>
+        Suffix Icon
+        <SlIcon slot="suffix" name="heart" />
+      </SlMenuItem>
+    </SlMenu>
+  </SlDropdown>  
+);
+```
+
 ## Examples
 
 ### Getting the Selected Item
@@ -60,6 +94,93 @@ When dropdowns are used with [menus](/components/menu), you can listen for the `
 </script>
 ```
 
+```jsx react
+import { 
+  SlButton,
+  SlDropdown,
+  SlMenu,
+  SlMenuItem
+} from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  function handleSelect(event) {
+    const selectedItem = event.detail.item;
+    console.log(selectedItem.value);
+  }
+
+  return (
+    <SlDropdown>
+      <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> 
+  );
+};
+```
+
+Alternatively, you can listen for the `click` event on individual menu items. Note that, using this approach, disabled menu items will still emit a `click` event.
+
+```html preview
+<div class="dropdown-selection-alt">
+  <sl-dropdown>
+    <sl-button slot="trigger" caret>Edit</sl-button>
+    <sl-menu>
+      <sl-menu-item value="cut">Cut</sl-menu-item>
+      <sl-menu-item value="copy">Copy</sl-menu-item>
+      <sl-menu-item value="paste">Paste</sl-menu-item>
+    </sl-menu>
+  </sl-dropdown>
+</div>
+
+<script>
+  const container = document.querySelector('.dropdown-selection-alt');
+  const cut = container.querySelector('sl-menu-item[value="cut"]');
+  const copy = container.querySelector('sl-menu-item[value="copy"]');
+  const paste = container.querySelector('sl-menu-item[value="paste"]');
+
+  cut.addEventListener('click', () => console.log('cut'));
+  copy.addEventListener('click', () => console.log('copy'));
+  paste.addEventListener('click', () => console.log('paste'));
+</script>
+```
+
+```jsx react
+import { 
+  SlButton,
+  SlDropdown,
+  SlMenu,
+  SlMenuItem
+} from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  function handleCut() {
+    console.log('cut');
+  }
+
+  function handleCopy() {
+    console.log('copy');
+  }
+
+  function handlePaste() {
+    console.log('paste');
+  }
+
+  return (
+    <SlDropdown>
+      <SlButton slot="trigger" caret>Edit</SlButton>
+      <SlMenu>
+        <SlMenuItem onClick={handleCut}>Cut</SlMenuItem>
+        <SlMenuItem onClick={handleCopy}>Copy</SlMenuItem>
+        <SlMenuItem onClick={handlePaste}>Paste</SlMenuItem>
+      </SlMenu>
+    </SlDropdown> 
+  );
+};
+```
+
 ### Placement
 
 The preferred placement of the dropdown can be set with the `placement` attribute. Note that the actual position may vary to ensure the panel remains in the viewport.
@@ -78,6 +199,30 @@ The preferred placement of the dropdown can be set with the `placement` attribut
 </sl-dropdown>
 ```
 
+```jsx 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>
+    <SlMenu>
+      <SlMenuItem>Cut</SlMenuItem>
+      <SlMenuItem>Copy</SlMenuItem>
+      <SlMenuItem>Paste</SlMenuItem>
+      <SlDivider />
+      <SlMenuItem>Find</SlMenuItem>
+      <SlMenuItem>Replace</SlMenuItem>
+    </SlMenu>
+  </SlDropdown> 
+);
+```
+
 ### Distance
 
 The distance from the panel to the trigger can be customized using the `distance` attribute. This value is specified in pixels.
@@ -96,6 +241,30 @@ The distance from the panel to the trigger can be customized using the `distance
 </sl-dropdown>
 ```
 
+```jsx react
+import { 
+  SlButton,
+  SlDivider,
+  SlDropdown,
+  SlMenu,
+  SlMenuItem
+} from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlDropdown distance={30}>
+    <SlButton slot="trigger" caret>Edit</SlButton>
+    <SlMenu>
+      <SlMenuItem>Cut</SlMenuItem>
+      <SlMenuItem>Copy</SlMenuItem>
+      <SlMenuItem>Paste</SlMenuItem>
+      <SlDivider />
+      <SlMenuItem>Find</SlMenuItem>
+      <SlMenuItem>Replace</SlMenuItem>
+    </SlMenu>
+  </SlDropdown> 
+);
+```
+
 ### Skidding
 
 The offset of the panel along the trigger can be customized using the `skidding` attribute. This value is specified in pixels.
@@ -114,6 +283,30 @@ The offset of the panel along the trigger can be customized using the `skidding`
 </sl-dropdown>
 ```
 
+```jsx react
+import { 
+  SlButton,
+  SlDivider,
+  SlDropdown,
+  SlMenu,
+  SlMenuItem
+} from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlDropdown skidding={30}>
+    <SlButton slot="trigger" caret>Edit</SlButton>
+    <SlMenu>
+      <SlMenuItem>Cut</SlMenuItem>
+      <SlMenuItem>Copy</SlMenuItem>
+      <SlMenuItem>Paste</SlMenuItem>
+      <SlDivider />
+      <SlMenuItem>Find</SlMenuItem>
+      <SlMenuItem>Replace</SlMenuItem>
+    </SlMenu>
+  </SlDropdown> 
+);
+```
+
 ### Hoisting
 
 Dropdown panels will be clipped if they're inside a container that has `overflow: auto|hidden`. The `hoist` attribute forces the panel to use a fixed positioning strategy, allowing it to break out of the container. In this case, the panel will be positioned relative to its containing block, which is usually the viewport unless an ancestor uses a `transform`, `perspective`, or `filter`. [Refer to this page](https://developer.mozilla.org/en-US/docs/Web/CSS/position#fixed) for more details.
@@ -141,11 +334,56 @@ Dropdown panels will be clipped if they're inside a container that has `overflow
 
 <style>
   .dropdown-hoist {
-    border: solid 2px rgb(var(--sl-panel-border-color));
+    border: solid 2px var(--sl-panel-border-color);
     padding: var(--sl-spacing-medium);
     overflow: hidden;
   }
 </style>
 ```
 
+```jsx react
+import { 
+  SlButton,
+  SlDivider,
+  SlDropdown,
+  SlIcon,
+  SlMenu,
+  SlMenuItem
+} from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .dropdown-hoist {
+    border: solid 2px var(--sl-panel-border-color);
+    padding: var(--sl-spacing-medium);
+    overflow: hidden;
+  }
+`;
+
+const App = () => (
+  <>
+    <div className="dropdown-hoist">
+      <SlDropdown>
+        <SlButton slot="trigger" caret>No Hoist</SlButton>
+        <SlMenu>
+          <SlMenuItem>Item 1</SlMenuItem>
+          <SlMenuItem>Item 2</SlMenuItem>
+          <SlMenuItem>Item 3</SlMenuItem>
+        </SlMenu>
+      </SlDropdown>
+
+      <SlDropdown hoist>
+        <SlButton slot="trigger" caret>Hoist</SlButton>
+        <SlMenu>
+          <SlMenuItem>Item 1</SlMenuItem>
+          <SlMenuItem>Item 2</SlMenuItem>
+          <SlMenuItem>Item 3</SlMenuItem>
+        </SlMenu>
+      </SlDropdown>
+    </div>
+
+    <style>{css}</style>
+  </>
+);
+```
+
 [component-metadata:sl-dropdown]

docs/components/form.md

@@ -1,215 +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');
-
-  // Watch for the slSubmit event
-  form.addEventListener('sl-submit', event => {
-    const formData = event.detail.formData;
-    let output = '';
-
-    //
-    // Example 1: 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);
-    });
-
-    //
-    // Example 2: Output all form control names + values
-    //
-    for (const entry of formData.entries()) {
-      output += `${entry[0]}: ${entry[1]}\n`;
-    }
-    alert(output);
-
-    //
-    // Example 3: Get all form controls that were serialized as 
-    // an array of HTML elements
-    //
-    console.log(event.detail.formControls);
-  });
-</script>
-```
-
-## 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>
-```
-
-### 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>
-```
-
-### 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>
-```
-
-### 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>
-```
-
-### 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: rgb(var(--sl-color-danger-600));
-  }
-
-  .custom-input[invalid]:not([disabled])::part(base) {      
-    border-color: rgb(var(--sl-color-danger-500));
-  } 
-
-  .custom-input[invalid]:focus-within::part(base) {
-    box-shadow: 0 0 0 var(--sl-focus-ring-width) rgb(var(--sl-color-danger-500) / var(--sl-focus-ring-alpha));
-  }
-</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

@@ -20,6 +20,34 @@ Formats a number as a human readable bytes value.
 </script>
 ```
 
+
+```jsx react
+import { useState } from 'react';
+import { 
+  SlButton, 
+  SlFormatBytes, 
+  SlInput 
+} from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [value, setValue] = useState(1000);
+
+  return (
+    <>
+      The file is <SlFormatBytes value={value} /> in size.
+      <br /><br />
+      <SlInput 
+        type="number" 
+        value={value}
+        label="Number to Format" 
+        style={{ maxWidth: '180px' }}
+        onSlInput={event => setValue(event.target.value)}
+      />
+    </>
+  );
+};
+```
+
 ## Examples
 
 ### Formatting Bytes
@@ -33,26 +61,66 @@ Set the `value` attribute to a number to get the value in bytes.
 <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="1200000000" />
+  </>
+);
+```
+
 ### 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
+import { SlFormatBytes } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlFormatBytes value="12" unit="bit" /><br />
+    <SlFormatBytes value="1200" unit="bit" /><br />
+    <SlFormatBytes value="1200000" unit="bit" /><br />
+    <SlFormatBytes value="1200000000" unit="bit" />
+  </>
+);
 ```
 
 ### Localization
 
-Use the `locale` attribute to set the number formatting locale.
+Use the `lang` attribute to set the number formatting locale.
 
 ```html preview
-<sl-format-bytes value="12" locale="de"></sl-format-bytes><br>
-<sl-format-bytes value="1200" locale="de"></sl-format-bytes><br>
-<sl-format-bytes value="1200000" locale="de"></sl-format-bytes><br>
-<sl-format-bytes value="1200000000" locale="de"></sl-format-bytes>
+<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>
+```
+
+```jsx react
+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="1200000000" lang="de" />
+  </>
+);
 ```
 
 [component-metadata:sl-format-bytes]

docs/components/format-date.md

@@ -11,11 +11,18 @@ Localization is handled by the browser's [`Intl.DateTimeFormat` API](https://dev
 <sl-format-date date="2020-07-15T09:17:00-04:00"></sl-format-date>
 ```
 
+```jsx react
+import { SlFormatDate } from '@shoelace-style/shoelace/dist/react';
+
+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.
 
 ?> 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.
 
-
 ## Examples
 
 ### Date & Time Formatting
@@ -42,6 +49,32 @@ Formatting options are based on those found in the [`Intl.DateTimeFormat` API](h
 <sl-format-date></sl-format-date>
 ```
 
+```jsx react
+import { SlFormatDate } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    {/* Human-readable date */}
+    <SlFormatDate month="long" day="numeric" year="numeric" /><br />
+
+    {/* Time */}
+    <SlFormatDate hour="numeric" minute="numeric" /><br />
+
+    {/* Weekday */}
+    <SlFormatDate weekday="long" /><br />
+
+    {/* Month */}
+    <SlFormatDate month="long" /><br />
+
+    {/* Year */}
+    <SlFormatDate year="numeric" /><br />
+
+    {/* No formatting options */}
+    <SlFormatDate />
+  </>
+);
+```
+
 ### Hour Formatting
 
 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`.
@@ -51,14 +84,37 @@ By default, the browser will determine whether to use 12-hour or 24-hour time. T
 <sl-format-date hour="numeric" minute="numeric" hour-format="24"></sl-format-date>
 ```
 
+```jsx react
+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="24" />
+  </>
+);
+```
+
 ### Localization
 
-Use the `locale` attribute to set the date/time formatting locale.
+Use the `lang` attribute to set the date/time formatting locale.
 
 ```html preview
-English: <sl-format-date locale="en"></sl-format-date><br>
-French: <sl-format-date locale="fr"></sl-format-date><br>
-Russian: <sl-format-date locale="ru"></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>
+```
+
+```jsx react
+import { SlFormatDate } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    English: <SlFormatDate lang="en" /><br />
+    French: <SlFormatDate lang="fr" /><br />
+    Russian: <SlFormatDate lang="ru" />
+  </>
+);
 ```
 
 [component-metadata:sl-format-date]

docs/components/format-number.md

@@ -22,6 +22,29 @@ Localization is handled by the browser's [`Intl.NumberFormat` API](https://devel
 </script>
 ```
 
+```jsx react
+import { useState } from 'react';
+import { SlFormatNumber, SlInput } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [value, setValue] = useState(1000);
+
+  return (
+    <>
+      <SlFormatNumber value={value} />
+      <br /><br />
+      <SlInput 
+        type="number" 
+        value={value} 
+        label="Number to Format" 
+        style={{ maxWidth: '180px' }}
+        onSlInput={event => setValue(event.target.value)}
+      />
+    </>
+  );
+};
+```
+
 ## Examples
 
 ### Percentages
@@ -30,32 +53,72 @@ 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=".25"></sl-format-number><br>
-<sl-format-number type="percent" value=".50"></sl-format-number><br>
-<sl-format-number type="percent" value=".75"></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>
 ```
 
+```jsx react
+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} />  
+  </>
+);
+```
+
 ### Localization
 
-Use the `locale` attribute to set the number formatting locale.
+Use the `lang` attribute to set the number formatting locale.
 
 ```html preview
-English: <sl-format-number value="2000" locale="en" minimum-fraction-digits="2"></sl-format-number><br>
-German: <sl-format-number value="2000" locale="de" minimum-fraction-digits="2"></sl-format-number><br>
-Russian: <sl-format-number value="2000" locale="ru" minimum-fraction-digits="2"></sl-format-number>
+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>
+```
+
+```jsx react
+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 />
+    Russian: <SlFormatNumber value="2000" lang="ru" minimum-fraction-digits="2" />
+  </>
+);
 ```
 
 ### Currency
 
-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 `locale` to ensure the the number is formatted correctly for the target locale.
+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" locale="en-US"></sl-format-number><br>
-<sl-format-number type="currency" currency="GBP" value="2000" locale="en-GB"></sl-format-number><br>
-<sl-format-number type="currency" currency="EUR" value="2000" locale="de"></sl-format-number><br>
-<sl-format-number type="currency" currency="RUB" value="2000" locale="ru"></sl-format-number><br>
-<sl-format-number type="currency" currency="CNY" value="2000" locale="zh-cn"></sl-format-number>
+<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>
+```
+
+```jsx react
+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="CNY" value="2000" lang="zh-cn" />
+  </>
+);
 ```
 
 [component-metadata:sl-format-number]

docs/components/icon-button.md

@@ -10,6 +10,14 @@ For a full list of icons that come bundled with Shoelace, refer to the [icon com
 <sl-icon-button name="gear" label="Settings"></sl-icon-button>
 ```
 
+```jsx react
+import { SlIconButton } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlIconButton name="gear" label="Settings" />
+);
+```
+
 ## Examples
 
 ### Sizes
@@ -22,6 +30,18 @@ Icon buttons inherit their parent element's `font-size`.
 <sl-icon-button name="pencil" label="Edit" style="font-size: 2.5rem;"></sl-icon-button>
 ```
 
+```jsx react
+import { SlIconButton } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlIconButton name="pencil" label="Edit" style={{ fontSize: '1.5rem' }} />
+    <SlIconButton name="pencil" label="Edit" style={{ fontSize: '2rem' }} />
+    <SlIconButton name="pencil" label="Edit" style={{ fontSize: '2.5rem' }} />
+  </>
+);
+```
+
 ### Colors
 
 Icon buttons are designed to have a uniform appearance, so their color is not inherited. However, you can still customize them by styling the `base` part.
@@ -49,6 +69,37 @@ Icon buttons are designed to have a uniform appearance, so their color is not in
 </style>
 ```
 
+```jsx react
+import { SlIconButton } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .icon-button-color sl-icon-button::part(base) {
+    color: #b00091;
+  }
+
+  .icon-button-color sl-icon-button::part(base):hover,
+  .icon-button-color sl-icon-button::part(base):focus {
+    color: #c913aa;
+  }
+
+  .icon-button-color sl-icon-button::part(base):active {
+    color: #960077;
+  }
+`;
+
+const App = () => (
+  <>
+    <div className="icon-button-color">
+      <SlIconButton name="type-bold" label="Bold" />
+      <SlIconButton name="type-italic" label="Italic" />
+      <SlIconButton name="type-underline" label="Underline" />
+    </div>
+
+    <style>{css}</style>
+  </>
+);
+```
+
 ### Link Buttons
 
 Use the `href` attribute to convert the button to a link.
@@ -57,6 +108,19 @@ Use the `href` attribute to convert the button to a link.
 <sl-icon-button name="gear" label="Settings" href="https://example.com" target="_blank"></sl-icon-button>
 ```
 
+```jsx react
+import { SlIconButton } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlIconButton 
+    name="gear" 
+    label="Settings" 
+    href="https://example.com" 
+    target="_blank"
+  />
+);
+```
+
 ### Icon Button with Tooltip
 
 Wrap a tooltip around an icon button to provide contextual information to the user.
@@ -67,6 +131,16 @@ Wrap a tooltip around an icon button to provide contextual information to the us
 </sl-tooltip>
 ```
 
+```jsx react
+import { SlIconButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTooltip content="Settings">
+    <SlIconButton name="gear" label="Settings" />
+  </SlTooltip>
+);
+```
+
 ### Disabled
 
 Use the `disabled` attribute to disable the icon button.
@@ -75,4 +149,12 @@ Use the `disabled` attribute to disable the icon button.
 <sl-icon-button name="gear" label="Settings" disabled></sl-icon-button>
 ```
 
+```jsx react
+import { SlIconButton } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlIconButton name="gear" label="Settings" disabled />
+);
+```
+
 [component-metadata:sl-icon-button]

docs/components/icon.md

@@ -4,7 +4,7 @@
 
 Icons are symbols that can be used to represent various options within an application.
 
-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.
+Shoelace comes bundled with over 1,500 icons courtesy of the [Bootstrap Icons](https://icons.getbootstrap.com/) project. These icons are part of the `default` icon library. If you prefer, you can register [custom icon libraries](#icon-libraries) as well.
 
 Click or tap on an icon below to copy its name and use it like this.
 
@@ -40,6 +40,7 @@ Icons are sized relative to the current font size. To change their size, set the
   <sl-icon name="battery-charging"></sl-icon>
   <sl-icon name="bell"></sl-icon>
   <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>
   <sl-icon name="flag"></sl-icon>
@@ -50,16 +51,65 @@ Icons are sized relative to the current font size. To change their size, set the
   <sl-icon name="search"></sl-icon>
   <sl-icon name="star"></sl-icon>
   <sl-icon name="trash"></sl-icon>
-  <sl-icon name="x-circle"></sl-icon>
 </div>
 ```
 
+```jsx react
+import { SlIcon } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <div style={{ fontSize: '32px' }}>
+    <SlIcon name="exclamation-triangle" />
+    <SlIcon name="archive" />
+    <SlIcon name="battery-charging" />
+    <SlIcon name="bell" />
+    <SlIcon name="clock" />
+    <SlIcon name="cloud" />
+    <SlIcon name="download" />
+    <SlIcon name="file-earmark" />
+    <SlIcon name="flag" />
+    <SlIcon name="heart" />
+    <SlIcon name="image" />
+    <SlIcon name="lightning" />
+    <SlIcon name="mic" />
+    <SlIcon name="search" />
+    <SlIcon name="star" />
+    <SlIcon name="trash" />
+  </div>  
+);
+```
+
+### Labels
+
+For non-decorative icons, use the `label` attribute to announce it to assistive devices.
+
+```html preview
+<sl-icon name="star-fill" label="Add to favorites"></sl-icon>
+```
+
+```jsx react
+import { SlIcon } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlIcon name="star-fill" label="Add to favorites" />
+);
+```
+
 ### Custom Icons
 
 Custom icons can be loaded individually with the `src` attribute. Only SVGs on a local or CORS-enabled endpoint are supported. If you're using more than one custom icon, it might make sense to register a [custom icon library](#icon-libraries).
 
 ```html preview
-<sl-icon src="/assets/images/shoe.svg" style="font-size: 8rem;"></sl-icon>
+<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>
+);
 ```
 
 ## Icon Libraries
@@ -141,27 +191,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>
 ```
@@ -509,7 +559,7 @@ If you want to change the icons Shoelace uses internally, you can register an ic
         item.setAttribute('data-name', i.name);
         item.setAttribute('data-terms', [i.name, i.title, ...(i.tags || []), ...(i.categories || [])].join(' '));
         item.innerHTML = `
-          <svg width="1em" height="1em">
+          <svg width="1em" height="1em" fill="currentColor">
             <use xlink:href="/assets/icons/sprite.svg#${i.name}"></use>
           </svg>      
         `;
@@ -558,7 +608,7 @@ If you want to change the icons Shoelace uses internally, you can register an ic
 
 <style>
   .icon-search {
-    border: solid 1px rgb(var(--sl-panel-border-color));
+    border: solid 1px var(--sl-panel-border-color);
     border-radius: var(--sl-border-radius-medium);
     padding: var(--sl-spacing-medium);
   }
@@ -614,8 +664,8 @@ If you want to change the icons Shoelace uses internally, you can register an ic
   }
 
   .icon-list-item:hover {
-    background-color: rgb(var(--sl-color-primary-50));
-    color: rgb(var(--sl-color-primary-600));
+    background-color: var(--sl-color-primary-50);
+    color: var(--sl-color-primary-600);
   }
 
   .icon-list[data-type="outline"] .icon-list-item[data-name$="-fill"] {

docs/components/image-comparer.md

@@ -13,6 +13,17 @@ For best results, use images that share the same dimensions. The slider can be c
 </sl-image-comparer>
 ```
 
+```jsx react
+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." />
+  </SlImageComparer>
+);
+```
+
 ## Examples
 
 ### Initial Position
@@ -26,4 +37,15 @@ Use the `position` attribute to set the initial position of the slider. This is
 </sl-image-comparer>
 ```
 
+```jsx react
+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." />
+  </SlImageComparer>
+);
+```
+
 [component-metadata:sl-image-comparer]

docs/components/include.md

@@ -8,8 +8,16 @@ Included files are asynchronously requested using `window.fetch()`. Requests are
 
 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.
 
-```html preview no-codepen
-<sl-include src="/assets/examples/include.html"></sl-include>
+```html preview
+<sl-include src="https://shoelace.style/assets/examples/include.html"></sl-include>
+```
+
+```jsx react
+import { SlInclude } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlInclude src="https://shoelace.style/assets/examples/include.html" />
+);
 ```
 
 ## Examples
@@ -21,7 +29,7 @@ When an include file loads successfully, the `sl-load` event will be emitted. Yo
 If the request fails, the `sl-error` event will be emitted. In this case, `event.detail.status` will contain the resulting HTTP status code of the request, e.g. 404 (not found).
 
 ```html
-<sl-include src="/assets/examples/include.html"></sl-include>
+<sl-include src="https://shoelace.style/assets/examples/include.html"></sl-include>
 
 <script>
   const include = document.querySelector('sl-include');

docs/components/input.md

@@ -8,9 +8,15 @@ Inputs collect data from the user.
 <sl-input></sl-input>
 ```
 
-?> This component doesn't work with standard forms. Use [`<sl-form>`](/components/form) instead.
+```jsx react
+import { SlInput } from '@shoelace-style/shoelace/dist/react';
 
-?> Please refer to the section on [form control validation](/components/form?id=form-control-validation) to learn how to do client-side validation.
+const App = () => (
+  <SlInput />
+);
+```
+
+?> 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
 
@@ -22,6 +28,14 @@ Use the `placeholder` attribute to add a placeholder.
 <sl-input placeholder="Type something"></sl-input>
 ```
 
+```jsx react
+import { SlInput } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlInput placeholder="Type something" />
+);
+```
+
 ### Clearable
 
 Add the `clearable` attribute to add a clear button when the input has content.
@@ -30,6 +44,14 @@ Add the `clearable` attribute to add a clear button when the input has content.
 <sl-input placeholder="Clearable" clearable></sl-input>
 ```
 
+```jsx react
+import { SlInput } from '@shoelace-style/shoelace/dist/react';
+
+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.
@@ -42,6 +64,20 @@ Add the `toggle-password` attribute to add a toggle button that will show the pa
 <sl-input type="password" placeholder="Password Toggle" size="large" toggle-password></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 />  
+  </>
+);
+```
+
 ### Filled Inputs
 
 Add the `filled` attribute to draw a filled input.
@@ -50,6 +86,14 @@ Add the `filled` attribute to draw a filled input.
 <sl-input placeholder="Type something" filled></sl-input>
 ```
 
+```jsx react
+import { SlInput } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlInput placeholder="Type something" filled />
+);
+```
+
 ### Pill
 
 Use the `pill` attribute to give inputs rounded edges.
@@ -62,6 +106,20 @@ Use the `pill` attribute to give inputs rounded edges.
 <sl-input placeholder="Large" size="large" pill></sl-input>
 ```
 
+```jsx react
+import { SlInput } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlInput placeholder="Small" size="small" pill />
+    <br />
+    <SlInput placeholder="Medium" size="medium" pill />
+    <br />
+    <SlInput placeholder="Large" size="large" pill />
+  </>
+);
+```
+
 ### Input Types
 
 The `type` attribute controls the type of input the browser renders.
@@ -74,6 +132,20 @@ The `type` attribute controls the type of input the browser renders.
 <sl-input type="date" Placeholder="Date"></sl-input>
 ```
 
+```jsx react
+import { SlInput } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlInput type="email" Placeholder="Email" />
+    <br />
+    <SlInput type="number" Placeholder="Number" />
+    <br />
+    <SlInput type="date" Placeholder="Date" />
+  </>
+);
+```
+
 ### Disabled
 
 Use the `disabled` attribute to disable an input.
@@ -86,6 +158,20 @@ Use the `disabled` attribute to disable an input.
 <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.
@@ -98,6 +184,20 @@ Use the `size` attribute to change an input's size.
 <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" />
+  </>
+);
+```
+
 ### Prefix & Suffix Icons
 
 Use the `prefix` and `suffix` slots to add icons.
@@ -119,6 +219,29 @@ Use the `prefix` and `suffix` slots to add icons.
 </sl-input>
 ```
 
+```jsx react
+import { SlIcon, SlInput } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlInput placeholder="Small" size="small">
+      <SlIcon name="house" slot="prefix"></SlIcon>
+      <SlIcon name="chat" slot="suffix"></SlIcon>
+    </SlInput>
+    <br />
+    <SlInput placeholder="Medium" size="medium">
+      <SlIcon name="house" slot="prefix"></SlIcon>
+      <SlIcon name="chat" slot="suffix"></SlIcon>
+    </SlInput>
+    <br />
+    <SlInput placeholder="Large" size="large">
+      <SlIcon name="house" slot="prefix"></SlIcon>
+      <SlIcon name="chat" slot="suffix"></SlIcon>
+    </SlInput>
+  </>
+);
+```
+
 ### Labels
 
 Use the `label` attribute to give the input an accessible label. For labels that contain HTML, use the `label` slot instead.
@@ -127,6 +250,14 @@ Use the `label` attribute to give the input an accessible label. For labels that
 <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.
@@ -138,4 +269,15 @@ Add descriptive help text to an input with the `help-text` attribute. For help t
 ></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?" 
+  />
+);
+```
+
 [component-metadata:sl-input]

docs/components/menu-item.md

@@ -5,7 +5,7 @@
 Menu items provide options for the user to pick from in a menu.
 
 ```html preview
-<sl-menu style="max-width: 200px; border: solid 1px rgb(var(--sl-panel-border-color)); border-radius: var(--sl-border-radius-medium);">
+<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>Option 2</sl-menu-item>
   <sl-menu-item>Option 3</sl-menu-item>
@@ -24,6 +24,41 @@ Menu items provide options for the user to pick from in a menu.
 </sl-menu>
 ```
 
+```jsx 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)'
+    }}
+  >
+    <SlMenuItem>Option 1</SlMenuItem>
+    <SlMenuItem>Option 2</SlMenuItem>
+    <SlMenuItem>Option 3</SlMenuItem>
+    <SlDivider />
+    <SlMenuItem checked>Checked</SlMenuItem>
+    <SlMenuItem disabled>Disabled</SlMenuItem>
+    <SlDivider />
+    <SlMenuItem>
+      Prefix Icon
+      <SlIcon slot="prefix" name="gift" />
+    </SlMenuItem>
+    <SlMenuItem>
+      Suffix Icon
+      <SlIcon slot="suffix" name="heart" />
+    </SlMenuItem>
+  </SlMenu>  
+);
+```
+
 ## Examples
 
 ### Checked
@@ -31,31 +66,73 @@ Menu items provide options for the user to pick from in a menu.
 Use the `checked` attribute to draw menu items in a checked state.
 
 ```html preview
-<sl-menu style="max-width: 200px; border: solid 1px rgb(var(--sl-panel-border-color)); border-radius: var(--sl-border-radius-medium);">
+<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 rgb(var(--sl-panel-border-color)); border-radius: var(--sl-border-radius-medium);">
+<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 disabled>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 disabled>Option 2</SlMenuItem>
+    <SlMenuItem>Option 3</SlMenuItem>
+  </SlMenu>  
+);
+```
+
 ### Prefix & Suffix
 
 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 rgb(var(--sl-panel-border-color)); border-radius: var(--sl-border-radius-medium);">
+<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>
     <sl-icon slot="prefix" name="house"></sl-icon>
     Home
@@ -64,7 +141,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>
@@ -76,12 +153,50 @@ Add content to the start and end of menu items using the `prefix` and `suffix` s
 </sl-menu>
 ```
 
+```jsx 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)'
+    }}
+  >
+    <SlMenuItem>
+      <SlIcon slot="prefix" name="house" />
+      Home
+    </SlMenuItem>
+
+    <SlMenuItem>
+      <SlIcon slot="prefix" name="envelope" />
+      Messages
+      <SlBadge slot="suffix" variant="primary" pill>12</SlBadge>
+    </SlMenuItem>
+
+    <SlDivider />
+
+    <SlMenuItem>
+      <SlIcon slot="prefix" name="gear" />
+      Settings
+    </SlMenuItem>
+  </SlMenu>  
+);
+```
+
 ### Value & Selection
 
 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 rgb(var(--sl-panel-border-color)); border-radius: var(--sl-border-radius-medium);">
+<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-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>
@@ -102,4 +217,39 @@ The `value` attribute can be used to assign a hidden value, such as a unique ide
 </script>
 ```
 
+```jsx react
+import { 
+  SlMenu,
+  SlMenuItem
+} from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+
+  function handleSelect(event) {
+    const item = event.detail.item;
+
+    // Toggle checked state
+    item.checked = !item.checked;
+
+    // Log value
+    console.log(`Selected value: ${item.value}`);
+  }
+
+  return (
+    <SlMenu 
+      style={{
+        maxWidth: '200px',
+        border: 'solid 1px var(--sl-panel-border-color)',
+        borderRadius: 'var(--sl-border-radius-medium)'
+      }}
+      onSlSelect={handleSelect}
+    >
+      <SlMenuItem value="opt-1">Option 1</SlMenuItem>
+      <SlMenuItem value="opt-2">Option 2</SlMenuItem>
+      <SlMenuItem value="opt-3">Option 3</SlMenuItem>
+    </SlMenu>
+  );
+};
+```
+
 [component-metadata:sl-menu-item]

docs/components/menu-label.md

@@ -6,7 +6,7 @@ Menu labels are used to describe a group of menu items.
 
 ```html preview
 <sl-menu
-  style="max-width: 200px; border: solid 1px rgb(var(--sl-panel-border-color)); border-radius: var(--sl-border-radius-medium);"
+  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-label>Fruits</sl-menu-label>
   <sl-menu-item value="apple">Apple</sl-menu-item>
@@ -20,4 +20,33 @@ Menu labels are used to describe a group of menu items.
 </sl-menu>
 ```
 
+```jsx 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)'
+    }}
+  >
+    <SlMenuLabel>Fruits</SlMenuLabel>
+    <SlMenuItem value="apple">Apple</SlMenuItem>
+    <SlMenuItem value="banana">Banana</SlMenuItem>
+    <SlMenuItem value="orange">Orange</SlMenuItem>
+    <SlDivider />
+    <SlMenuLabel>Vegetables</SlMenuLabel>
+    <SlMenuItem value="broccoli">Broccoli</SlMenuItem>
+    <SlMenuItem value="carrot">Carrot</SlMenuItem>
+    <SlMenuItem value="zucchini">Zucchini</SlMenuItem>
+  </SlMenu>  
+);
+```
+
 [component-metadata:sl-menu-label]

docs/components/menu.md

@@ -7,7 +7,7 @@ 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 rgb(var(--sl-panel-border-color)); border-radius: var(--sl-border-radius-medium);">
+<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 value="undo">Undo</sl-menu-item>
   <sl-menu-item value="redo">Redo</sl-menu-item>
   <sl-divider></sl-divider>
@@ -18,6 +18,32 @@ You can use [menu items](/components/menu-item), [menu labels](/components/menu-
 </sl-menu>
 ```
 
+```jsx 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)'
+    }}
+  >
+    <SlMenuItem value="undo">Undo</SlMenuItem>
+    <SlMenuItem value="redo">Redo</SlMenuItem>
+    <SlDivider />
+    <SlMenuItem value="cut">Cut</SlMenuItem>
+    <SlMenuItem value="copy">Copy</SlMenuItem>
+    <SlMenuItem value="paste">Paste</SlMenuItem>
+    <SlMenuItem value="delete">Delete</SlMenuItem>
+  </SlMenu>  
+);
+```
+
 ?> Menus are intended for system menus (dropdown menus, select menus, context menus, etc.). They should not be mistaken for navigation menus which serve a different purpose and have a different semantic meaning. If you're building navigation, use `<nav>` and `<a>` elements instead.
 
 [component-metadata:sl-menu]

docs/components/mutation-observer.md

@@ -8,8 +8,8 @@ The mutation observer will report changes to the content it wraps through the `s
 
 ```html preview
 <div class="mutation-overview">
-  <sl-mutation-observer attr>
-    <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>
@@ -19,13 +19,13 @@ The mutation observer will report changes to the content it wraps through the `s
     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
@@ -42,6 +42,47 @@ The mutation observer will report changes to the content it wraps through the `s
 </div>
 ```
 
+```jsx react
+import { useState } from 'react';
+import { SlButton, SlMutationObserver } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .resize-observer-overview div {
+    display: flex; 
+    border: solid 2px var(--sl-input-border-color); 
+    align-items: center; 
+    justify-content: center;
+    text-align: center;
+    padding: 4rem 2rem;
+  }
+`;
+
+const variants = ['primary', 'success', 'neutral', 'warning', 'danger']; 
+let clicks = 0;
+
+const App = () => {
+  const [variant, setVariant] = useState('primary');
+
+  function handleClick() {
+    clicks++;
+    setVariant(variants[clicks % variants.length]);
+  }
+
+  return (
+    <>
+      <SlMutationObserver 
+        attr="*"
+        onSlMutation={event => console.log(event.detail)}
+      >
+        <SlButton variant={variant} onClick={handleClick}>Click to mutate</SlButton>
+      </SlMutationObserver>
+
+      <style>{css}</style>
+    </>
+  );
+};
+```
+
 ?> When you create a mutation observer, you must indicate what changes it should respond to by including at least one of `attr`, `child-list`, or `char-data`. If you don't specify at least one of these attributes, no mutation events will be emitted.
 
 ## Examples
@@ -54,7 +95,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>
 
@@ -64,7 +105,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
@@ -76,7 +117,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) {
@@ -101,4 +142,55 @@ Use the `child-list` attribute to watch for new child elements that are added or
 </div>
 ```
 
+```jsx react
+import { useState } from 'react';
+import { SlButton, SlMutationObserver } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .mutation-child-list .buttons {
+    display: flex;
+    gap: .25rem;
+    flex-wrap: wrap;
+    margin-bottom: 1rem;
+  }
+`;
+
+let buttonCount = 0;
+
+const App = () => {
+  const [buttonIds, setButtonIds] = useState([]);
+
+  function addButton() {
+    setButtonIds([...buttonIds, ++buttonCount]);
+  }
+
+  function removeButton(id) {
+    setButtonIds(buttonIds.filter(i => i !== id));
+  }
+
+  return (
+    <>
+      <div className="mutation-child-list">
+        <SlMutationObserver 
+          child-list 
+          onSlMutation={event => console.log(event.detail)}
+        >
+          <div className="buttons">
+            <SlButton variant="primary" onClick={addButton}>Add button</SlButton>
+            {buttonIds.map(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>
+    </>
+  );
+};
+```
+
 [component-metadata:sl-mutation-observer]

docs/components/progress-bar.md

@@ -8,6 +8,14 @@ Progress bars are used to show the status of an ongoing operation.
 <sl-progress-bar value="50"></sl-progress-bar>
 ```
 
+```jsx react
+import { SlProgressBar } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlProgressBar value={50} />
+);
+```
+
 ## Examples
 
 ### Custom Height
@@ -18,6 +26,17 @@ Use the `--height` custom property to set the progress bar's height.
 <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.
@@ -26,6 +45,17 @@ Use the `label` attribute to label the progress bar and tell assistive devices h
 <sl-progress-bar value="50" label="Upload progress"></sl-progress-bar>
 ```
 
+```jsx react
+import { SlProgressBar } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlProgressBar
+    value="50" 
+    label="Upload progress"
+  />
+);
+```
+
 ### Showing Values
 
 Use the default slot to show a value.
@@ -57,6 +87,44 @@ Use the default slot to show a value.
 </script>
 ```
 
+```jsx react
+import { useState } from 'react';
+import { 
+  SlButton,
+  SlIcon,
+  SlProgressBar
+} from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [value, setValue] = useState(50);
+
+  function adjustValue(amount) {
+    let newValue = value + amount;
+    if (newValue < 0) newValue = 0;
+    if (newValue > 100) newValue = 100;
+    setValue(newValue);
+  }
+
+  return (
+    <>
+      <SlProgressBar value={value}>
+        {value}%
+      </SlProgressBar>
+
+      <br />
+
+      <SlButton circle onClick={() => adjustValue(-10)}>
+        <SlIcon name="dash" />
+      </SlButton>
+
+      <SlButton circle onClick={() => adjustValue(10)}>
+        <SlIcon name="plus" />
+      </SlButton>
+    </>
+  );
+};
+```
+
 ### Indeterminate
 
 The `indeterminate` attribute can be used to inform the user that the operation is pending, but its status cannot currently be determined. In this state, `value` is ignored and the label, if present, will not be shown.
@@ -65,4 +133,12 @@ The `indeterminate` attribute can be used to inform the user that the operation
 <sl-progress-bar indeterminate></sl-progress-bar>
 ```
 
+```jsx react
+import { SlProgressBar } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlProgressBar indeterminate />
+);
+```
+
 [component-metadata:sl-progress-bar]

docs/components/progress-ring.md

@@ -8,6 +8,14 @@ Progress rings are used to show the progress of a determinate operation in a cir
 <sl-progress-ring value="25"></sl-progress-ring>
 ```
 
+```jsx react
+import { SlProgressRing } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlProgressRing value="25" />
+);
+```
+
 ## Examples
 
 ### Size
@@ -18,6 +26,17 @@ Use the `--size` custom property to set the diameter of the progress ring.
 <sl-progress-ring value="50" style="--size: 200px;"></sl-progress-ring>
 ```
 
+```jsx react
+import { SlProgressRing } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlProgressRing 
+    value="50" 
+    style={{ '--size': '200px' }}
+  />
+);
+```
+
 ### Track Width
 
 Use the `--track-width` custom property to set the width of the progress ring's track.
@@ -26,6 +45,17 @@ Use the `--track-width` custom property to set the width of the progress ring's
 <sl-progress-ring value="50" style="--track-width: 10px;"></sl-progress-ring>
 ```
 
+```jsx react
+import { SlProgressRing } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlProgressRing 
+    value="50" 
+    style={{ '--track-width': '10px' }}
+  />
+);
+```
+
 ### Colors
 
 To change the color, use the `--track-color` and `--indicator-color` custom properties.
@@ -40,6 +70,20 @@ To change the color, use the `--track-color` and `--indicator-color` custom prop
 ></sl-progress-ring>
 ```
 
+```jsx react
+import { SlProgressRing } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlProgressRing 
+    value="50" 
+    style={{ 
+      '--track-color': 'pink',
+      '--indicator-color': 'deeppink'
+    }}
+  />
+);
+```
+
 ### Labels
 
 Use the `label` attribute to label the progress ring and tell assistive devices how to announce it.
@@ -48,9 +92,20 @@ Use the `label` attribute to label the progress ring and tell assistive devices
 <sl-progress-ring value="50" label="Upload progress"></sl-progress-ring>
 ```
 
+```jsx react
+import { SlProgressRing } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlProgressRing 
+    value="50" 
+    label="Upload progress"
+  />
+);
+```
+
 ### Showing Values
 
-Use the default slot to show a label.
+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>
@@ -79,4 +134,45 @@ Use the default slot to show a label.
 </script>
 ```
 
+```jsx react
+import { useState } from 'react';
+import { 
+  SlButton,
+  SlIcon,
+  SlProgressRing
+} from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [value, setValue] = useState(50);
+
+  function adjustValue(amount) {
+    let newValue = value + amount;
+    if (newValue < 0) newValue = 0;
+    if (newValue > 100) newValue = 100;
+    setValue(newValue);
+  }
+
+  return (
+    <>
+      <SlProgressRing 
+        value={value} 
+        style={{ marginBottom: '.5rem' }}
+      >
+        {value}%
+      </SlProgressRing>
+
+      <br />
+
+      <SlButton circle onClick={() => adjustValue(-10)}>
+        <SlIcon name="dash" />
+      </SlButton>
+
+      <SlButton circle onClick={() => adjustValue(10)}>
+        <SlIcon name="plus" />
+      </SlButton>
+    </>
+  );
+};
+```
+
 [component-metadata:sl-progress-ring]

docs/components/qr-code.md

@@ -34,6 +34,38 @@ QR codes are useful for providing small pieces of information to users who can q
 </style>
 ```
 
+```jsx react
+import { useState } from 'react';
+import { SlQrCode, SlInput } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .qr-overview {
+    max-width: 256px;
+  }
+
+  .qr-overview sl-input {
+    margin-top: 1rem;
+  }
+`;
+
+const App = () => {
+  const [value, setValue] = useState('https://shoelace.style/');
+
+  return (
+    <>
+      <div className="qr-overview">
+        <SlQrCode value={value} label="Scan this code to visit Shoelace on the web!" />
+        <br />
+
+        <SlInput maxlength="255" clearable onInput={event => setValue(event.target.value)} />
+      </div>
+
+      <style>{css}</style>
+    </>
+  );
+};
+```
+
 ## Examples
 
 ### Colors
@@ -44,6 +76,14 @@ Use the `fill` and `background` attributes to modify the QR code's colors. You s
 <sl-qr-code value="https://shoelace.style/" fill="deeppink" background="white"></sl-qr-code>
 ```
 
+```jsx react
+import { SlQrCode } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlQrCode value="https://shoelace.style/" fill="deeppink" background="white" />
+);
+```
+
 ### Size
 
 Use the `size` attribute to change the size of the QR code.
@@ -52,6 +92,14 @@ Use the `size` attribute to change the size of the QR code.
 <sl-qr-code value="https://shoelace.style/" size="64"></sl-qr-code>
 ```
 
+```jsx react
+import { SlQrCode } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlQrCode value="https://shoelace.style/" size="64" />
+);
+```
+
 ### Radius
 
 Create a rounded effect with the `radius` attribute.
@@ -60,6 +108,14 @@ Create a rounded effect with the `radius` attribute.
 <sl-qr-code value="https://shoelace.style/" radius="0.5"></sl-qr-code>
 ```
 
+```jsx react
+import { SlQrCode } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlQrCode value="https://shoelace.style/" radius="0.5" />
+);
+```
+
 ### Error Correction
 
 QR codes can be rendered with various levels of [error correction](https://www.qrcode.com/en/about/error_correction.html) that can be set using the `error-correction` attribute. This example generates four codes with the same value using different error correction levels.
@@ -81,4 +137,31 @@ QR codes can be rendered with various levels of [error correction](https://www.q
 </style>
 ```
 
+```jsx react
+import { SlQrCode } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .qr-error-correction {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 1rem;
+  }
+`;
+
+const App = () => {
+  return (
+    <>
+      <div className="qr-error-correction">
+        <SlQrCode value="https://shoelace.style/" error-correction="L" />
+        <SlQrCode value="https://shoelace.style/" error-correction="M" />
+        <SlQrCode value="https://shoelace.style/" error-correction="Q" />
+        <SlQrCode value="https://shoelace.style/" error-correction="H" />
+      </div>
+
+      <style>{css}</style>
+    </>
+  );
+};
+```
+
 [component-metadata:sl-qr-code]

docs/components/radio-group.md

@@ -5,13 +5,25 @@
 Radio Groups are used to group multiple radios so they function as a single control.
 
 ```html preview
-<sl-radio-group label="Select an item">
-  <sl-radio value="1" checked>Item 1</sl-radio>
-  <sl-radio value="2">Item 2</sl-radio>
-  <sl-radio value="3">Item 3</sl-radio>
+<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 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">
+    <SlRadio value="1" checked>Option 1</SlRadio>
+    <SlRadio value="2">Option 2</SlRadio>
+    <SlRadio value="3">Option 3</SlRadio>
+  </SlRadioGroup>
+);
+```
+
 ## Examples
 
 ### Showing the Fieldset
@@ -19,11 +31,22 @@ Radio Groups are used to group multiple radios so they function as a single cont
 You can show a fieldset and legend that wraps the radio group using the `fieldset` attribute.
 
 ```html preview
-<sl-radio-group label="Select an item" fieldset>
-  <sl-radio value="1" checked>Item 1</sl-radio>
-  <sl-radio value="2">Item 2</sl-radio>
-  <sl-radio value="3">Item 3</sl-radio>
+<sl-radio-group label="Select an option" fieldset>
+  <sl-radio value="1" checked>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" fieldset>
+    <SlRadio value="1" checked>Option 1</SlRadio>
+    <SlRadio value="2">Option 2</SlRadio>
+    <SlRadio value="3">Option 3</SlRadio>
+  </SlRadioGroup>
+);
+```
 [component-metadata:sl-radio-group]

docs/components/radio.md

@@ -7,14 +7,26 @@ 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.
 
 ```html preview
-<sl-radio-group label="Select an option" no-fieldset>
+<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 value="3">Option 3</sl-radio>
 </sl-radio-group>
 ```
 
-?> This component doesn't work with standard forms. Use [`<sl-form>`](/components/form) instead.
+```jsx react
+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>
+    <SlRadio value="3">Option 3</SlRadio>
+  </SlRadioGroup>
+);
+```
+
+?> 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
 
@@ -23,7 +35,7 @@ Radios are designed to be used with [radio groups](/components/radio-group). As
 Use the `disabled` attribute to disable a radio.
 
 ```html preview
-<sl-radio-group label="Select an option" no-fieldset>
+<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 value="3">Option 3</sl-radio>
@@ -31,4 +43,17 @@ Use the `disabled` attribute to disable a radio.
 </sl-radio-group>
 ```
 
+```jsx react
+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>
+    <SlRadio value="3">Option 3</SlRadio>
+    <SlRadio value="4" disabled>Disabled</SlRadio>
+  </SlRadioGroup>
+);
+```
+
 [component-metadata:sl-radio]

docs/components/range.md

@@ -8,16 +8,49 @@ Ranges allow the user to select a single value within a given range using a slid
 <sl-range></sl-range>
 ```
 
-?> This component doesn't work with standard forms. Use [`<sl-form>`](/components/form) instead.
+```jsx react
+import { SlRange } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRange />
+);
+```
+
+?> 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
 
+### 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.
+
+```html preview
+<sl-range min="0" max="10" step="1"></sl-range>
+```
+
+```jsx react
+import { SlRange } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRange min={0} max={10} step={1} />
+);
+```
+
 ### Disabled
 
 Use the `disabled` attribute to disable a slider.
 
 ```html preview
-<sl-range min="0" max="100" step="1" disabled></sl-range>
+<sl-range disabled></sl-range>
+```
+
+
+```jsx react
+import { SlRange } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRange disabled />
+);
 ```
 
 ### Tooltip Placement
@@ -25,7 +58,15 @@ Use the `disabled` attribute to disable a slider.
 By default, the tooltip is shown on top. Set `tooltip` to `bottom` to show it below the slider.
 
 ```html preview
-<sl-range min="0" max="100" step="1" tooltip="bottom"></sl-range>
+<sl-range tooltip="bottom"></sl-range>
+```
+
+```jsx react
+import { SlRange } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRange tooltip="bottom" />
+);
 ```
 
 ### Disable the Tooltip
@@ -33,7 +74,15 @@ By default, the tooltip is shown on top. Set `tooltip` to `bottom` to show it be
 To disable the tooltip, set `tooltip` to `none`.
 
 ```html preview
-<sl-range min="0" max="100" step="1" tooltip="none"></sl-range>
+<sl-range tooltip="none"></sl-range>
+```
+
+```jsx react
+import { SlRange } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRange tooltip="none" />
+);
 ```
 
 ### Custom Track Colors
@@ -42,11 +91,24 @@ You can customize the active and inactive portions of the track using the `--tra
 
 ```html preview
 <sl-range style="
-  --track-color-active: rgb(var(--sl-color-primary-600));
-  --track-color-inactive: rgb(var(--sl-color-primary-200));
+  --track-color-active: var(--sl-color-primary-600);
+  --track-color-inactive: var(--sl-color-primary-100);
 "></sl-range>
 ```
 
+```jsx react
+import { SlRange } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRange 
+    style={{
+      '--track-color-active': 'var(--sl-color-primary-600)',
+      '--track-color-inactive': 'var(--sl-color-primary-200)'
+    }}
+  />
+);
+```
+
 ### 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.
@@ -60,6 +122,19 @@ You can change the tooltip's content by setting the `tooltipFormatter` property
 </script>
 ```
 
+```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.
@@ -68,6 +143,14 @@ Use the `label` attribute to give the range an accessible label. For labels that
 <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.
@@ -81,4 +164,17 @@ Add descriptive help text to a range with the `help-text` attribute. For help te
 ></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}
+  />
+);
+```
+
 [component-metadata:sl-range]

docs/components/rating.md

@@ -8,6 +8,14 @@ Ratings give users a way to quickly view and provide feedback.
 <sl-rating></sl-rating>
 ```
 
+```jsx react
+import { SlRating } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRating />
+);
+```
+
 ## Examples
 
 ### Maximum Value
@@ -18,12 +26,28 @@ Ratings are 0-5 by default. To change the maximum possible value, use the `max`
 <sl-rating max="3"></sl-rating>
 ```
 
+```jsx react
+import { SlRating } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRating max={3} />
+);
+```
+
 ### Precision
 
 Use the `precision` attribute to let users select fractional ratings.
 
 ```html preview
-<sl-rating precision=".5" value="2.5"></sl-rating>
+<sl-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} />
+);
 ```
 
 ## Symbol Sizes
@@ -34,6 +58,14 @@ Set the `--symbol-size` custom property to adjust the size.
 <sl-rating style="--symbol-size: 2rem;"></sl-rating>
 ```
 
+```jsx react
+import { SlRating } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRating style={{ '--symbol-size': '2rem' }} />
+);
+```
+
 ### Readonly
 
 Use the `readonly` attribute to display a rating that users can't change.
@@ -42,6 +74,14 @@ Use the `readonly` attribute to display a rating that users can't change.
 <sl-rating readonly value="3"></sl-rating>
 ```
 
+```jsx react
+import { SlRating } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRating readonly value={3} />
+);
+```
+
 ### Disabled
 
 Use the `disable` attribute to disable the rating.
@@ -50,6 +90,14 @@ Use the `disable` attribute to disable the rating.
 <sl-rating disabled value="3"></sl-rating>
 ```
 
+```jsx react
+import { SlRating } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRating disabled value={3} />
+);
+```
+
 ### Custom Icons
 
 ```html preview
@@ -61,6 +109,18 @@ Use the `disable` attribute to disable the rating.
 </script>
 ```
 
+```jsx react
+import '@shoelace-style/shoelace/dist/components/icon/icon';
+import { SlRating } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlRating 
+    getSymbol={() => '<sl-icon name="heart-fill"></sl-icon>'}
+    style={{ '--symbol-color-active': '#ff4136' }} 
+  />
+);
+```
+
 ### Value-based Icons
 
 ```html preview
@@ -76,4 +136,18 @@ Use the `disable` attribute to disable the rating.
 </script>
 ```
 
+```jsx react
+import '@shoelace-style/shoelace/dist/components/icon/icon';
+import { SlRating } from '@shoelace-style/shoelace/dist/react';
+
+function getSymbol(value) {
+  const icons = ['emoji-angry', 'emoji-frown', 'emoji-expressionless', 'emoji-smile', 'emoji-laughing'];
+  return `<sl-icon name="${icons[value - 1]}"></sl-icon>`;
+}
+
+const App = () => (
+  <SlRating getSymbol={getSymbol} />
+);
+```
+
 [component-metadata:sl-rating]

docs/components/relative-time.md

@@ -11,6 +11,14 @@ Localization is handled by the browser's [`Intl.RelativeTimeFormat` API](https:/
 <sl-relative-time date="2020-07-15T09:17:00-04:00"></sl-relative-time>
 ```
 
+```jsx react
+import { SlRelativeTime } from '@shoelace-style/shoelace/dist/react';
+
+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.
@@ -36,6 +44,16 @@ Use the `sync` attribute to update the displayed value automatically as time pas
 </script>
 ```
 
+```jsx react
+import { SlRelativeTime } from '@shoelace-style/shoelace/dist/react';
+
+const date = new Date(new Date().getTime() - 60000);
+
+const App = () => (
+  <SlRelativeTime date={date} sync />
+);
+```
+
 ### Formatting Styles
 
 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.
@@ -46,16 +64,42 @@ You can change how the time is displayed using the `format` attribute. Note that
 <sl-relative-time date="2020-07-15T09:17:00-04:00" format="long"></sl-relative-time>
 ```
 
+```jsx react
+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="long" />
+  </>
+);
+```
+
 ### Localization
 
-Use the `locale` attribute to set the desired locale.
+Use the `lang` attribute to set the desired locale.
 
 ```html preview
-English: <sl-relative-time date="2020-07-15T09:17:00-04:00" locale="en-US"></sl-relative-time><br>
-Chinese: <sl-relative-time date="2020-07-15T09:17:00-04:00" locale="zh-CN"></sl-relative-time><br>
-German: <sl-relative-time date="2020-07-15T09:17:00-04:00" locale="de"></sl-relative-time><br>
-Greek: <sl-relative-time date="2020-07-15T09:17:00-04:00" locale="el"></sl-relative-time><br>
-Russian: <sl-relative-time date="2020-07-15T09:17:00-04:00" locale="ru"></sl-relative-time>
+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>
+```
+
+```jsx react
+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 />
+    Russian: <SlRelativeTime date="2020-07-15T09:17:00-04:00" lang="ru" />
+  </>
+);
 ```
 
 [component-metadata:sl-relative-time]

docs/components/resize-observer.md

@@ -27,7 +27,7 @@ The resize observer will report changes to the dimensions of the elements it wra
 <style>
   .resize-observer-overview div {
     display: flex; 
-    border: solid 2px rgb(var(--sl-input-border-color)); 
+    border: solid 2px var(--sl-input-border-color); 
     align-items: center; 
     justify-content: center;
     text-align: center;
@@ -36,4 +36,33 @@ The resize observer will report changes to the dimensions of the elements it wra
 </style>
 ```
 
+```jsx react
+import { SlResizeObserver } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .resize-observer-overview div {
+    display: flex; 
+    border: solid 2px var(--sl-input-border-color); 
+    align-items: center; 
+    justify-content: center;
+    text-align: center;
+    padding: 4rem 2rem;
+  }
+`;
+
+const App = () => (
+  <>
+    <div className="resize-observer-overview">
+      <SlResizeObserver onSlResize={event => console.log(event.detail)}>
+        <div>
+          Resize this box and watch the console 👉
+        </div>
+      </SlResizeObserver>
+    </div>
+
+    <style>{css}</style>
+  </>
+);
+```
+
 [component-metadata:sl-resize-observer]

docs/components/responsive-media.md

@@ -12,6 +12,19 @@ You can slot in any [replaced element](https://developer.mozilla.org/en-US/docs/
 </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
@@ -24,6 +37,19 @@ The following image maintains a `4:3` aspect ratio as its container is resized.
 </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.
@@ -34,4 +60,14 @@ The following video is embedded using an `iframe` and maintains a `16:9` aspect
 </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

@@ -16,7 +16,23 @@ Selects allow you to choose one or more items from a dropdown menu.
 </sl-select>
 ```
 
-?> This component doesn't work with standard forms. Use [`<sl-form>`](/components/form) instead.
+```jsx react
+import { SlDivider, SlMenuItem, 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>
+  </SlSelect>
+);
+```
+
+?> 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
 
@@ -32,6 +48,18 @@ Use the `placeholder` attribute to add a placeholder.
 </sl-select>
 ```
 
+```jsx react
+import { SlMenuItem, 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>
+  </SlSelect>
+);
+```
+
 ### Clearable
 
 Use the `clearable` attribute to make the control clearable.
@@ -44,6 +72,18 @@ Use the `clearable` attribute to make the control clearable.
 </sl-select>
 ```
 
+```jsx react
+import { SlMenuItem, 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>
+  </SlSelect>
+);
+```
+
 ### Filled Selects
 
 Add the `filled` attribute to draw a filled select.
@@ -56,6 +96,18 @@ Add the `filled` attribute to draw a filled select.
 </sl-select>
 ```
 
+```jsx react
+import { SlMenuItem, 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>
+  </SlSelect>
+);
+```
+
 ### Pill
 
 Use the `pill` attribute to give selects rounded edges.
@@ -68,6 +120,18 @@ Use the `pill` attribute to give selects rounded edges.
 </sl-select>
 ```
 
+```jsx react
+import { SlMenuItem, 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>
+  </SlSelect>
+);
+```
+
 ### Disabled
 
 Use the `disabled` attribute to disable a select.
@@ -80,9 +144,21 @@ Use the `disabled` attribute to disable a select.
 </sl-select>
 ```
 
+```jsx react
+import { SlMenuItem, 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>
+  </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. When using this option, the `value` property will be an array of strings instead of a string.
 
 ```html preview
 <sl-select placeholder="Select a few" multiple clearable>
@@ -96,6 +172,24 @@ To allow multiple options to be selected, use the `multiple` attribute. It's a g
 </sl-select>
 ```
 
+```jsx react
+import { SlDivider, SlMenuItem, 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>
+);
+```
+
+?> When using the `multiple` attribute, the `value` property will be an array instead of a string. To set it in your HTML, obtain a reference to the element and set `value` to an array of strings.
+
 ### Grouping Options
 
 Options can be grouped visually using menu labels and dividers.
@@ -114,6 +208,24 @@ Options can be grouped visually using menu labels and dividers.
 </sl-select>
 ```
 
+```jsx react
+import { SlDivider, SlMenuItem, SlMenuLabel, 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>
+);
+```
+
 ### Sizes
 
 Use the `size` attribute to change a select's size.
@@ -142,13 +254,43 @@ Use the `size` attribute to change a select's size.
 </sl-select>
 ```
 
+```jsx react
+import { SlMenuItem, 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>
+
+    <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>
+
+    <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>
+  </>
+);
+```
+
 ### Selecting Options Programmatically
 
 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.
 
 ```html preview
 <div class="selecting-example">
-  <sl-select placeholder="">
+  <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>
@@ -173,6 +315,31 @@ The `value` property is bound to the current selection. As the selection changes
 </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.
@@ -185,6 +352,18 @@ Use the `label` attribute to give the select an accessible label. For labels tha
 </sl-select>
 ```
 
+```jsx react
+import { SlMenuItem, 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>
+);
+```
+
 ### 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.
@@ -194,12 +373,27 @@ Add descriptive help text to a select with the `help-text` attribute. For help t
   label="Experience" 
   help-text="Please tell us your skill level."
 >
-  <sl-menu-item value="option-1">Novice</sl-menu-item>
-  <sl-menu-item value="option-2">Intermediate</sl-menu-item>
-  <sl-menu-item value="option-3">Advanced</sl-menu-item>
+  <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>
 ```
 
+```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.
@@ -230,4 +424,36 @@ Use the `prefix` and `suffix` slots to add icons.
 </sl-select>
 ```
 
+```jsx react
+import { SlIcon, SlMenuItem, 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>
+    </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>
+    </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>
+    </SlSelect>
+  </>
+);
+```
+
 [component-metadata:sl-select]

docs/components/skeleton.md

@@ -54,6 +54,60 @@ Skeletons try not to be opinionated, as there are endless possibilities for desi
 </style>
 ```
 
+```jsx react
+import { SlSkeleton } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .skeleton-overview header {
+    display: flex;
+    align-items: center;
+    margin-bottom: 1rem;
+  }
+
+  .skeleton-overview header sl-skeleton:last-child {
+    flex: 0 0 auto;
+    width: 30%;
+  }
+
+  .skeleton-overview sl-skeleton {
+    margin-bottom: 1rem;
+  }
+
+  .skeleton-overview sl-skeleton:nth-child(1) {
+    float: left;
+    width: 3rem;
+    height: 3rem;
+    margin-right: 1rem;
+    vertical-align: middle;
+  }
+
+  .skeleton-overview sl-skeleton:nth-child(3) {
+    width: 95%;
+  }
+
+  .skeleton-overview sl-skeleton:nth-child(4) {
+    width: 80%;
+  }
+`;
+
+const App = () => (
+  <>
+    <div className="skeleton-overview">
+      <header>
+        <SlSkeleton />
+        <SlSkeleton />
+      </header>
+
+      <SlSkeleton />
+      <SlSkeleton />
+      <SlSkeleton />
+    </div>  
+
+    <style>{css}</style>
+  </>
+);
+```
+
 ## Examples
 
 ### Effects
@@ -83,6 +137,37 @@ There are two built-in effects, `sheen` and `pulse`. Effects are intentionally s
 </style>
 ```
 
+```jsx react
+import { SlSkeleton } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .skeleton-effects {
+    font-size: var(--sl-font-size-small);
+  }
+
+  .skeleton-effects sl-skeleton:not(:first-child) {
+    margin-top: 1rem;
+  }
+`;
+
+const App = () => (
+  <>
+    <div className="skeleton-effects">
+      <SlSkeleton effect="none" />
+      None
+
+      <SlSkeleton effect="sheen" />
+      Sheen
+
+      <SlSkeleton effect="pulse" />
+      Pulse
+    </div>
+
+    <style>{css}</style>
+  </>
+);
+```
+
 ### Paragraphs
 
 Use multiple skeletons and some clever styles to simulate paragraphs.
@@ -115,6 +200,42 @@ Use multiple skeletons and some clever styles to simulate paragraphs.
 </style>
 ```
 
+```jsx react
+import { SlSkeleton } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .skeleton-paragraphs sl-skeleton {
+    margin-bottom: 1rem;
+  }
+
+  .skeleton-paragraphs sl-skeleton:nth-child(2) {
+    width: 95%;
+  }
+
+  .skeleton-paragraphs sl-skeleton:nth-child(4) {
+    width: 90%;
+  }
+
+  .skeleton-paragraphs sl-skeleton:last-child {
+    width: 50%;
+  }
+`;
+
+const App = () => (
+  <>
+    <div className="skeleton-paragraphs">
+      <SlSkeleton />
+      <SlSkeleton />
+      <SlSkeleton />
+      <SlSkeleton />
+      <SlSkeleton />
+    </div>
+
+    <style>{css}</style>
+  </>
+);
+```
+
 ### Avatars
 
 Set a matching width and height to make a circle, square, or rounded avatar skeleton.
@@ -144,6 +265,39 @@ Set a matching width and height to make a circle, square, or rounded avatar skel
 </style>
 ```
 
+```jsx react
+import { SlSkeleton } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .skeleton-avatars sl-skeleton {
+    display: inline-block;
+    width: 3rem;
+    height: 3rem;
+    margin-right: .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);
+  }
+`;
+
+const App = () => (
+  <>
+    <div className="skeleton-avatars">
+      <SlSkeleton />
+      <SlSkeleton />
+      <SlSkeleton />
+    </div>
+
+    <style>{css}</style>
+  </>
+);
+```
+
 ### Custom Shapes
 
 Use the `--border-radius` custom property to make circles, squares, and rectangles. For more complex shapes, you can apply `clip-path` to the `indicator` part. [Try Clippy](https://bennettfeely.com/clippy/) if you need help generating custom shapes.
@@ -193,6 +347,59 @@ Use the `--border-radius` custom property to make circles, squares, and rectangl
 </style>
 ```
 
+```jsx react
+import { SlSkeleton } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .skeleton-shapes sl-skeleton {
+    display: inline-flex;
+    width: 50px;
+    height: 50px;
+  }
+
+  .skeleton-shapes .square::part(indicator) {
+    --border-radius: var(--sl-border-radius-medium);
+  }
+
+  .skeleton-shapes .circle::part(indicator) {
+    --border-radius: var(--sl-border-radius-circle);
+  }
+
+  .skeleton-shapes .triangle::part(indicator) {
+    --border-radius: 0;
+    clip-path: polygon(50% 0, 0 100%, 100% 100%);
+  }
+
+  .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%);
+  }
+
+  .skeleton-shapes .comment::part(indicator) {
+    --border-radius: 0;
+    clip-path: polygon(0% 0%, 100% 0%, 100% 75%, 75% 75%, 75% 100%, 50% 75%, 0% 75%);
+  }
+
+  .skeleton-shapes sl-skeleton:not(:last-child) {
+    margin-right: .5rem;
+  }
+`;
+
+const App = () => (
+  <>
+  <div className="skeleton-shapes">
+    <SlSkeleton className="square" />
+    <SlSkeleton className="circle" />
+    <SlSkeleton className="triangle" />
+    <SlSkeleton className="cross" />
+    <SlSkeleton className="comment" />
+  </div>
+
+    <style>{css}</style>
+  </>
+);
+```
+
 ### Custom Colors
 
 Set the `--color` and `--sheen-color` custom properties to adjust the skeleton's color.
@@ -201,4 +408,32 @@ Set the `--color` and `--sheen-color` custom properties to adjust the skeleton's
 <sl-skeleton effect="sheen" style="--color: tomato; --sheen-color: #ffb094;"></sl-skeleton>
 ```
 
+```jsx react
+import { SlSkeleton } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .skeleton-avatars sl-skeleton {
+    display: inline-block;
+    width: 3rem;
+    height: 3rem;
+    margin-right: .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);
+  }
+`;
+
+const App = () => (
+  <SlSkeleton 
+    effect="sheen" 
+    style={{ '--color': 'tomato', '--sheen-color': '#ffb094' }} 
+  />
+);
+```
+
 [component-metadata:sl-skeleton]

docs/components/spinner.md

@@ -8,6 +8,14 @@ Spinners are used to show the progress of an indeterminate operation.
 <sl-spinner></sl-spinner>
 ```
 
+```jsx react
+import { SlSpinner } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlSpinner />
+);
+```
+
 ## Examples
 
 ### Size
@@ -20,12 +28,37 @@ Spinners are sized based on the current font size. To change their size, set the
 <sl-spinner style="font-size: 3rem;"></sl-spinner>
 ```
 
+```jsx react
+import { SlSpinner } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlSpinner />
+    <SlSpinner style={{ fontSize: '2rem' }} />
+    <SlSpinner style={{ fontSize: '3rem' }} />
+  </>
+);
+```
+
 ### Track Width
 
 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 
+    style={{
+      fontSize: '3rem',
+      '--track-width': '6px'
+    }} 
+  />
+);
 ```
 
 ### Color
@@ -36,4 +69,18 @@ The spinner's colors can be changed by setting the `--indicator-color` and `--tr
 <sl-spinner style="font-size: 3rem; --indicator-color: deeppink; --track-color: pink;"></sl-spinner>
 ```
 
+```jsx react
+import { SlSpinner } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlSpinner 
+    style={{
+      fontSize: '3rem',
+      '--indicator-color': 'deeppink',
+      '--track-color': 'pink'
+    }} 
+  />
+);
+```
+
 [component-metadata:sl-spinner]

docs/components/split-panel.md

@@ -0,0 +1,671 @@
+# Split Panel
+
+[component-header:sl-split-panel]
+
+Split panels display two adjacent panels, allowing the user to reposition them.
+
+```html preview
+<sl-split-panel>
+  <div slot="start" style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;">
+    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-menu-item value="">None</sl-menu-item>
+    <sl-menu-item value="start">Start</sl-menu-item>
+    <sl-menu-item value="end">End</sl-menu-item>
+  </sl-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 handle, slot an icon or another element into the `handle` slot. When customizing the divider, make sure to think about focus styles for keyboard users.
+
+```html preview
+<sl-split-panel style="--divider-width: 20px;">
+  <sl-icon slot="handle" name="grip-vertical"></sl-icon>
+  <div slot="start" style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;">
+    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="handle" 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-handle">
+  <sl-split-panel>
+    <sl-icon slot="handle" name="grip-vertical"></sl-icon>
+    <div slot="start" style="height: 200px; background: var(--sl-color-neutral-50); display: flex; align-items: center; justify-content: center;">
+      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-handle sl-split-panel {
+    --divider-width: 2px;
+  }
+
+  .split-panel-handle sl-split-panel::part(divider) {
+    background-color: var(--sl-color-pink-600);
+  }
+
+  .split-panel-handle 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-handle sl-split-panel::part(divider):focus-visible {
+    background-color: var(--sl-color-primary-600);
+  }
+
+  .split-panel-handle 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-handle sl-split-panel {
+    --divider-width: 2px;
+  }
+
+  .split-panel-handle sl-split-panel::part(divider) {
+    background-color: var(--sl-color-pink-600);
+  }
+
+  .split-panel-handle 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-handle sl-split-panel::part(divider):focus-visible {
+    background-color: var(--sl-color-primary-600);
+  }
+
+  .split-panel-handle 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-handle">
+    <SlSplitPanel>
+      <SlIcon slot="handle" 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

@@ -8,7 +8,15 @@ Switches allow the user to toggle an option on or off.
 <sl-switch>Switch</sl-switch>
 ```
 
-?> This component doesn't work with standard forms. Use [`<sl-form>`](/components/form) instead.
+```jsx react
+import { SlSwitch } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlSwitch>Switch</SlSwitch>
+);
+```
+
+?> 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
 
@@ -20,6 +28,14 @@ Use the `checked` attribute to activate the switch.
 <sl-switch checked>Checked</sl-switch>
 ```
 
+```jsx react
+import { SlSwitch } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlSwitch checked>Checked</SlSwitch>
+);
+```
+
 ### Disabled
 
 Use the `disabled` attribute to disable the switch.
@@ -28,6 +44,14 @@ Use the `disabled` attribute to disable the switch.
 <sl-switch disabled>Disabled</sl-switch>
 ```
 
+```jsx react
+import { SlSwitch } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlSwitch disabled>Disabled</SlSwitch>
+);
+```
+
 ### Custom Size
 
 Use the available custom properties to make the switch a different size.
@@ -36,4 +60,18 @@ Use the available custom properties to make the switch a different size.
 <sl-switch style="--width: 80px; --height: 32px; --thumb-size: 26px;"></sl-switch>
 ```
 
+```jsx react
+import { SlSwitch } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlSwitch 
+    style={{
+      '--width': '80px',
+      '--height': '32px',
+      '--thumb-size': '26px'
+    }} 
+  />
+);
+```
+
 [component-metadata:sl-switch]

docs/components/tab-group.md

@@ -20,6 +20,24 @@ Tab groups make use of [tabs](/components/tab) and [tab panels](/components/tab-
 </sl-tab-group>
 ```
 
+```jsx react
+import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/react';
+
+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>
+
+    <SlTabPanel name="general">This is the general tab panel.</SlTabPanel>
+    <SlTabPanel name="custom">This is the custom tab panel.</SlTabPanel>
+    <SlTabPanel name="advanced">This is the advanced tab panel.</SlTabPanel>
+    <SlTabPanel name="disabled">This is a disabled tab panel.</SlTabPanel>
+  </SlTabGroup>
+);
+```
+
 ## Examples
 
 ### Tabs on Bottom
@@ -40,6 +58,24 @@ Tabs can be shown on the bottom by setting `placement` to `bottom`.
 </sl-tab-group>
 ```
 
+```jsx react
+import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/react';
+
+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>
+
+    <SlTabPanel name="general">This is the general tab panel.</SlTabPanel>
+    <SlTabPanel name="custom">This is the custom tab panel.</SlTabPanel>
+    <SlTabPanel name="advanced">This is the advanced tab panel.</SlTabPanel>
+    <SlTabPanel name="disabled">This is a disabled tab panel.</SlTabPanel>
+  </SlTabGroup>
+);
+```
+
 ### Tabs on Start
 
 Tabs can be shown on the starting side by setting `placement` to `start`.
@@ -58,6 +94,25 @@ 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>
+
+    <SlTabPanel name="general">This is the general tab panel.</SlTabPanel>
+    <SlTabPanel name="custom">This is the custom tab panel.</SlTabPanel>
+    <SlTabPanel name="advanced">This is the advanced tab panel.</SlTabPanel>
+    <SlTabPanel name="disabled">This is a disabled tab panel.</SlTabPanel>
+  </SlTabGroup>
+);
+```
+
 ### Tabs on End
 
 Tabs can be shown on the ending side by setting `placement` to `end`.
@@ -76,6 +131,25 @@ 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>
+
+    <SlTabPanel name="general">This is the general tab panel.</SlTabPanel>
+    <SlTabPanel name="custom">This is the custom tab panel.</SlTabPanel>
+    <SlTabPanel name="advanced">This is the advanced tab panel.</SlTabPanel>
+    <SlTabPanel name="disabled">This is a disabled tab panel.</SlTabPanel>
+  </SlTabGroup>
+);
+```
+
 ### Closable Tabs
 
 Add the `closable` attribute to a tab to show a close button. This example shows how you can dynamically remove tabs from the DOM when the close button is activated.
@@ -112,6 +186,40 @@ Add the `closable` attribute to a tab to show a close button. This example shows
 </script>
 ```
 
+```jsx react
+import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  function handleClose(event) {
+    //
+    // 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>
+
+      <SlTabPanel name="general">This is the general tab panel.</SlTabPanel>
+      <SlTabPanel name="closable-1">This is the first closable tab panel.</SlTabPanel>
+      <SlTabPanel name="closable-2">This is the second closable tab panel.</SlTabPanel>
+      <SlTabPanel name="closable-3">This is the third closable tab panel.</SlTabPanel>
+    </SlTabGroup>
+  );
+};
+```
+
 ### Scrolling Tabs
 
 When there are more tabs than horizontal space allows, the nav will be scrollable.
@@ -162,6 +270,56 @@ When there are more tabs than horizontal space allows, the nav will be scrollabl
 </sl-tab-group>
 ```
 
+```jsx react
+import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/react';
+
+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>
+
+    <SlTabPanel name="tab-1">Tab panel 1</SlTabPanel>
+    <SlTabPanel name="tab-2">Tab panel 2</SlTabPanel>
+    <SlTabPanel name="tab-3">Tab panel 3</SlTabPanel>
+    <SlTabPanel name="tab-4">Tab panel 4</SlTabPanel>
+    <SlTabPanel name="tab-5">Tab panel 5</SlTabPanel>
+    <SlTabPanel name="tab-6">Tab panel 6</SlTabPanel>
+    <SlTabPanel name="tab-7">Tab panel 7</SlTabPanel>
+    <SlTabPanel name="tab-8">Tab panel 8</SlTabPanel>
+    <SlTabPanel name="tab-9">Tab panel 9</SlTabPanel>
+    <SlTabPanel name="tab-10">Tab panel 10</SlTabPanel>
+    <SlTabPanel name="tab-11">Tab panel 11</SlTabPanel>
+    <SlTabPanel name="tab-12">Tab panel 12</SlTabPanel>
+    <SlTabPanel name="tab-13">Tab panel 13</SlTabPanel>
+    <SlTabPanel name="tab-14">Tab panel 14</SlTabPanel>
+    <SlTabPanel name="tab-15">Tab panel 15</SlTabPanel>
+    <SlTabPanel name="tab-16">Tab panel 16</SlTabPanel>
+    <SlTabPanel name="tab-17">Tab panel 17</SlTabPanel>
+    <SlTabPanel name="tab-18">Tab panel 18</SlTabPanel>
+    <SlTabPanel name="tab-19">Tab panel 19</SlTabPanel>
+    <SlTabPanel name="tab-20">Tab panel 20</SlTabPanel>
+  </SlTabGroup>
+);
+```
+
 ### Manual Activation
 
 When focused, keyboard users can press <kbd>Left</kbd> or <kbd>Right</kbd> to select the desired tab. By default, the corresponding tab panel will be shown immediately (automatic activation). You can change this behavior by setting `activation="manual"` which will require the user to press <kbd>Space</kbd> or <kbd>Enter</kbd> before showing the tab panel (manual activation).
@@ -180,4 +338,22 @@ When focused, keyboard users can press <kbd>Left</kbd> or <kbd>Right</kbd> to se
 </sl-tab-group>
 ```
 
+```jsx react
+import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/react';
+
+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>
+
+    <SlTabPanel name="general">This is the general tab panel.</SlTabPanel>
+    <SlTabPanel name="custom">This is the custom tab panel.</SlTabPanel>
+    <SlTabPanel name="advanced">This is the advanced tab panel.</SlTabPanel>
+    <SlTabPanel name="disabled">This is a disabled tab panel.</SlTabPanel>
+  </SlTabGroup>
+);
+```
+
 [component-metadata:sl-tab-group]

docs/components/tab-panel.md

@@ -18,6 +18,24 @@ Tab panels are used inside [tab groups](/components/tab-group) to display tabbed
 </sl-tab-group>
 ```
 
+```jsx react
+import { SlTab, SlTabGroup, SlTabPanel } from '@shoelace-style/shoelace/dist/react';
+
+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>
+
+    <SlTabPanel name="general">This is the general tab panel.</SlTabPanel>
+    <SlTabPanel name="custom">This is the custom tab panel.</SlTabPanel>
+    <SlTabPanel name="advanced">This is the advanced tab panel.</SlTabPanel>
+    <SlTabPanel name="disabled">This is a disabled tab panel.</SlTabPanel>
+  </SlTabGroup>
+);
+```
+
 ?> Additional demonstrations can be found in the [tab group examples](/components/tab-group).
 
 [component-metadata:sl-tab-panel]

docs/components/tab.md

@@ -11,6 +11,19 @@ Tabs are used inside [tab groups](/components/tab-group) to represent and activa
 <sl-tab disabled>Disabled</sl-tab>
 ```
 
+```jsx react
+import { SlTab } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlTab>Tab</SlTab>
+    <SlTab active>Active</SlTab>
+    <SlTab closable>Closable</SlTab>
+    <SlTab disabled>Disabled</SlTab>
+  </>
+);
+```
+
 ?> Additional demonstrations can be found in the [tab group examples](/components/tab-group).
 
 [component-metadata:sl-tab]

docs/components/tag.md

@@ -5,11 +5,26 @@
 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 variant="primary">Primary</SlTag>
+    <SlTag variant="success">Success</SlTag>
+    <SlTag variant="neutral">Neutral</SlTag>
+    <SlTag variant="warning">Warning</SlTag>
+    <SlTag variant="danger">Danger</SlTag> 
+  </>
+);
 ```
 
 ## Examples
@@ -24,6 +39,18 @@ Use the `size` attribute to change a tab's size.
 <sl-tag size="large">Large</sl-tag>
 ```
 
+```jsx react
+import { SlTag } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlTag size="small">Small</SlTag>
+    <SlTag size="medium">Medium</SlTag>
+    <SlTag size="large">Large</SlTag>
+  </>
+);
+```
+
 ### Pill
 
 Use the `pill` attribute to give tabs rounded edges.
@@ -34,6 +61,18 @@ Use the `pill` attribute to give tabs rounded edges.
 <sl-tag size="large" pill>Large</sl-tag>
 ```
 
+```jsx react
+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>
+  </>
+);
+```
+
 ### Removable
 
 Use the `removable` attribute to add a remove button to the tag.
@@ -62,4 +101,42 @@ Use the `removable` attribute to add a remove button to the tag.
 </style>
 ```
 
+```jsx react
+import { SlTag } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .tags-removable sl-tag {
+    transition: var(--sl-transition-medium) opacity;
+  }
+`;
+
+const App = () => {
+  function handleRemove(event) {
+    const tag = event.target;
+    tag.style.opacity = '0';
+    setTimeout(() => tag.style.opacity = '1', 2000);
+  }
+
+  return (
+    <>
+      <div className="tags-removable">
+        <SlTag size="small" removable onSlRemove={handleRemove}>
+          Small
+        </SlTag>
+
+        <SlTag size="medium" removable onSlRemove={handleRemove}>
+          Medium
+        </SlTag>
+
+        <SlTag size="large" removable onSlRemove={handleRemove}>
+          Large
+        </SlTag>
+      </div>
+
+      <style>{css}</style>
+    </>
+  )
+};
+```
+
 [component-metadata:sl-tag]

docs/components/textarea.md

@@ -8,9 +8,15 @@ Textareas collect data from the user and allow multiple lines of text.
 <sl-textarea></sl-textarea>
 ```
 
-?> This component doesn't work with standard forms. Use [`<sl-form>`](/components/form) instead.
+```jsx react
+import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
 
-?> Please refer to the section on [form control validation](/components/form?id=form-control-validation) to learn how to do client-side validation.
+const App = () => (
+  <SlTextarea />
+);
+```
+
+?> 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
 
@@ -22,6 +28,14 @@ Use the `rows` attribute to change the number of text rows that get shown.
 <sl-textarea rows="2"></sl-textarea>
 ```
 
+```jsx react
+import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTextarea rows={2} />
+);
+```
+
 ### Placeholders
 
 Use the `placeholder` attribute to add a placeholder.
@@ -30,6 +44,14 @@ Use the `placeholder` attribute to add a placeholder.
 <sl-textarea placeholder="Type something"></sl-textarea>
 ```
 
+```jsx react
+import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTextarea placeholder="Type something" />
+);
+```
+
 ### Filled Textareas
 
 Add the `filled` attribute to draw a filled textarea.
@@ -38,6 +60,14 @@ Add the `filled` attribute to draw a filled textarea.
 <sl-textarea placeholder="Type something" filled></sl-textarea>
 ```
 
+```jsx react
+import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTextarea placeholder="Type something" filled />
+);
+```
+
 ### Disabled
 
 Use the `disabled` attribute to disable a textarea.
@@ -46,6 +76,14 @@ Use the `disabled` attribute to disable a textarea.
 <sl-textarea placeholder="Textarea" disabled></sl-textarea>
 ```
 
+```jsx react
+import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTextarea placeholder="Textarea" disabled />
+);
+```
+
 ### Sizes
 
 Use the `size` attribute to change a textarea's size.
@@ -58,6 +96,20 @@ Use the `size` attribute to change a textarea's size.
 <sl-textarea placeholder="Large" size="large"></sl-textarea>
 ```
 
+```jsx react
+import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <>
+    <SlTextarea placeholder="Small" size="small"></SlTextarea>
+    <br />
+    <SlTextarea placeholder="Medium" size="medium"></SlTextarea>
+    <br />
+    <SlTextarea placeholder="Large" size="large"></SlTextarea>
+  </>
+);
+```
+
 ### Labels
 
 Use the `label` attribute to give the textarea an accessible label. For labels that contain HTML, use the `label` slot instead.
@@ -66,6 +118,14 @@ Use the `label` attribute to give the textarea an accessible label. For labels t
 <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.
@@ -78,6 +138,17 @@ Add descriptive help text to a textarea with the `help-text` attribute. For help
 </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`.
@@ -86,6 +157,14 @@ By default, textareas can be resized vertically by the user. To prevent resizing
 <sl-textarea resize="none"></sl-textarea>
 ```
 
+```jsx react
+import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTextarea resize="none" />
+);
+```
+
 ### Expand with Content
 
 Textareas will automatically resize to expand to fit their content when `resize` is set to `auto`.
@@ -94,4 +173,12 @@ Textareas will automatically resize to expand to fit their content when `resize`
 <sl-textarea resize="auto"></sl-textarea>
 ```
 
+```jsx react
+import { SlTextarea } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTextarea resize="auto" />
+);
+```
+
 [component-metadata:sl-textarea]

docs/components/tooltip.md

@@ -14,6 +14,16 @@ Tooltips use `display: contents` so they won't interfere with how elements are p
 </sl-tooltip>
 ```
 
+```jsx react
+import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTooltip content="This is a tooltip">
+    <SlButton>Hover Me</SlButton>
+  </SlTooltip>  
+);
+```
+
 ## Examples
 
 ### Placement
@@ -41,7 +51,7 @@ Use the `placement` attribute to set the preferred placement of the tooltip.
       <sl-button></sl-button>
     </sl-tooltip>
 
-    <sl-tooltip content="right-start" placement="right-start" style="margin-left: 400px;">
+    <sl-tooltip content="right-start" placement="right-start">
       <sl-button></sl-button>
     </sl-tooltip>
   </div>
@@ -99,17 +109,119 @@ Use the `placement` attribute to set the preferred placement of the tooltip.
     margin-bottom: 0.25rem;
   }
 
-  .tooltip-placement-example [placement='top-start'] sl-button,
-  .tooltip-placement-example [placement='bottom-start'] sl-button {
+  .tooltip-placement-example-row:nth-child(1) sl-tooltip:first-child sl-button,
+  .tooltip-placement-example-row:nth-child(5) sl-tooltip:first-child sl-button {
     margin-left: calc(40px + 0.25rem);
   }
 
-  .tooltip-placement-example [placement^='right'] sl-button {
+  .tooltip-placement-example-row:nth-child(2) sl-tooltip:nth-child(2) sl-button,
+  .tooltip-placement-example-row:nth-child(3) sl-tooltip:nth-child(2) sl-button,
+  .tooltip-placement-example-row:nth-child(4) sl-tooltip:nth-child(2) sl-button {
     margin-left: calc((40px * 3) + (0.25rem * 3));
   }
 </style>
 ```
 
+```jsx react
+import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .tooltip-placement-example {
+    width: 250px;
+  }
+
+  .tooltip-placement-example-row:after {
+    content: '';
+    display: table;
+    clear: both;
+  }
+
+  .tooltip-placement-example sl-button {
+    float: left;
+    width: 2.5rem;
+    margin-right: 0.25rem;
+    margin-bottom: 0.25rem;
+  }
+
+  .tooltip-placement-example-row:nth-child(1) sl-tooltip:first-child sl-button,
+  .tooltip-placement-example-row:nth-child(5) sl-tooltip:first-child sl-button {
+    margin-left: calc(40px + 0.25rem);
+  }
+
+  .tooltip-placement-example-row:nth-child(2) sl-tooltip:nth-child(2) sl-button,
+  .tooltip-placement-example-row:nth-child(3) sl-tooltip:nth-child(2) sl-button,
+  .tooltip-placement-example-row:nth-child(4) sl-tooltip:nth-child(2) sl-button {
+    margin-left: calc((40px * 3) + (0.25rem * 3));
+  }
+`;
+
+const App = () => (
+  <>
+    <div className="tooltip-placement-example">
+      <div className="tooltip-placement-example-row">
+        <SlTooltip content="top-start" placement="top-start">
+          <SlButton />
+        </SlTooltip>
+
+        <SlTooltip content="top" placement="top">
+          <SlButton />
+        </SlTooltip>
+
+        <SlTooltip content="top-end" placement="top-end">
+          <SlButton />
+        </SlTooltip>
+      </div>
+
+      <div className="tooltip-placement-example-row">
+        <SlTooltip content="left-start" placement="left-start">
+          <SlButton />
+        </SlTooltip>
+
+        <SlTooltip content="right-start" placement="right-start">
+          <SlButton />
+        </SlTooltip>
+      </div>
+
+      <div className="tooltip-placement-example-row">
+        <SlTooltip content="left" placement="left">
+          <SlButton />
+        </SlTooltip>
+
+        <SlTooltip content="right" placement="right">
+          <SlButton />
+        </SlTooltip>
+      </div>
+
+      <div className="tooltip-placement-example-row">
+        <SlTooltip content="left-end" placement="left-end">
+          <SlButton />
+        </SlTooltip>
+
+        <SlTooltip content="right-end" placement="right-end">
+          <SlButton />
+        </SlTooltip>
+      </div>
+
+      <div className="tooltip-placement-example-row">
+        <SlTooltip content="bottom-start" placement="bottom-start">
+          <SlButton />
+        </SlTooltip>
+
+        <SlTooltip content="bottom" placement="bottom">
+          <SlButton />
+        </SlTooltip>
+
+        <SlTooltip content="bottom-end" placement="bottom-end">
+          <SlButton />
+        </SlTooltip>
+      </div>
+    </div>
+
+    <style>{css}</style>
+  </>
+);
+```
+
 ### Click Trigger
 
 Set the `trigger` attribute to `click` to toggle the tooltip on click instead of hover.
@@ -120,6 +232,16 @@ Set the `trigger` attribute to `click` to toggle the tooltip on click instead of
 </sl-tooltip>
 ```
 
+```jsx react
+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>  
+);
+```
+
 ### Manual Trigger
 
 Tooltips can be controller programmatically by setting the `trigger` attribute to `manual`. Use the `open` attribute to control when the tooltip is shown.
@@ -139,6 +261,30 @@ Tooltips can be controller programmatically by setting the `trigger` attribute t
 </script>
 ```
 
+```jsx react
+import { useState } from 'react';
+import { SlAvatar, SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <SlButton
+        style={{ marginRight: '4rem' }}
+        onClick={() => setOpen(!open)}
+      >
+        Toggle Manually
+      </SlButton>
+
+      <SlTooltip open={open} content="This is an avatar" trigger="manual">
+        <SlAvatar />
+      </SlTooltip>
+    </>
+  );
+};
+```
+
 ### Remove Arrows
 
 You can control the size of tooltip arrows by overriding the `--sl-tooltip-arrow-size` design token.
@@ -155,6 +301,22 @@ You can control the size of tooltip arrows by overriding the `--sl-tooltip-arrow
 </div>
 ```
 
+```jsx react
+import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <div style={{ '--sl-tooltip-arrow-size': '0' }}>
+    <SlTooltip content="This is a tooltip">
+      <SlButton>Above</SlButton>
+    </SlTooltip>
+
+    <SlTooltip content="This is a tooltip" placement="bottom">
+      <SlButton>Below</SlButton>
+    </SlTooltip>
+  </div>
+);
+```
+
 To override it globally, set it in a root block in your stylesheet after the Shoelace stylesheet is loaded.
 
 ```css
@@ -169,11 +331,28 @@ 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>
 ```
 
+```jsx react
+import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => (
+  <SlTooltip content="This is a tooltip">
+    <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>  
+);
+```
+
 ### Hoisting
 
 Tooltips will be clipped if they're inside a container that has `overflow: auto|hidden|scroll`. The `hoist` attribute forces the tooltip to use a fixed positioning strategy, allowing it to break out of the container. In this case, the tooltip will be positioned relative to its containing block, which is usually the viewport unless an ancestor uses a `transform`, `perspective`, or `filter`. [Refer to this page](https://developer.mozilla.org/en-US/docs/Web/CSS/position#fixed) for more details.
@@ -191,7 +370,7 @@ Tooltips will be clipped if they're inside a container that has `overflow: auto|
 
 <style>
   .tooltip-hoist {
-    border: solid 2px rgb(var(--sl-panel-border-color));
+    border: solid 2px var(--sl-panel-border-color);
     overflow: hidden;
     padding: var(--sl-spacing-medium);
     position: relative;
@@ -199,4 +378,33 @@ Tooltips will be clipped if they're inside a container that has `overflow: auto|
 </style>
 ```
 
+```jsx react
+import { SlButton, SlTooltip } from '@shoelace-style/shoelace/dist/react';
+
+const css = `
+  .tooltip-hoist {
+    border: solid 2px var(--sl-panel-border-color);
+    overflow: hidden;
+    padding: var(--sl-spacing-medium);
+    position: relative;
+  }
+`;
+
+const App = () => (
+  <>
+    <div class="tooltip-hoist">
+      <SlTooltip content="This is a tooltip">
+        <SlButton>No Hoist</SlButton>
+      </SlTooltip>
+
+      <SlTooltip content="This is a tooltip" hoist>
+        <SlButton>Hoist</SlButton>
+      </SlTooltip>
+    </div>
+
+    <style>{css}</style>
+  </>
+);
+```
+
 [component-metadata:sl-tooltip]

docs/components/visually-hidden.md

@@ -0,0 +1,47 @@
+# Visually Hidden
+
+[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;">
+  <sl-visually-hidden>
+    <a href="#">Skip to main content</a>
+  </sl-visually-hidden>
+</div>
+```
+
+## Examples
+
+### Links That Open in New Windows
+
+In this example, the link will open a new window. Screen readers will announce "opens in a new window" even though the text content isn't visible to sighted users.
+
+```html preview
+<a href="https://example.com/" target="_blank">
+  Visit External Page
+  <sl-icon name="box-arrow-up-right"></sl-icon>
+  <sl-visually-hidden>opens in a new window</sl-visually-hidden>
+</a>
+```
+
+### 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.
+
+```html preview
+<sl-card style="width: 100%; max-width: 360px;">
+  <header>
+    <sl-visually-hidden>Personal Info</sl-visually-hidden>
+  </header>
+  <sl-input label="Name" style="margin-bottom: .5rem;"></sl-input>
+  <sl-input label="Email" type="email"></sl-input>
+</sl-card>
+```
+
+[component-metadata:sl-visually-hidden]

docs/frameworks/angular.md

@@ -0,0 +1,46 @@
+# Angular
+
+Angular [plays nice](https://custom-elements-everywhere.com/#angular) with custom elements, so you can use Shoelace in your Angular apps with ease.
+
+## Installation
+
+To add Shoelace to your Angular 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
+
+Then make sure to apply the custom elements schema as shown below.
+
+```js
+import { BrowserModule } from '@angular/platform-browser';
+import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+
+import { AppComponent } from './app.component';
+
+@NgModule({
+  declarations: [AppComponent],
+  imports: [BrowserModule],
+  providers: [],
+  bootstrap: [AppComponent],
+  schemas: [CUSTOM_ELEMENTS_SCHEMA]
+})
+export class AppModule {}
+```
+
+Now you can start using Shoelace components in your app!
+
+?> Are you using Shoelace with Angular? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/angular.md)

docs/frameworks/react.md

@@ -0,0 +1,156 @@
+# React
+
+Shoelace offers a React version of every component to provide an idiomatic experience for React users. You can easily toggle between HTML and React examples throughout the documentation.
+
+## Installation
+
+To add Shoelace to your React 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
+// App.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](https://webpack.js.org/plugins/copy-webpack-plugin/) that copies `node_modules/@shoelace-style/shoelace/dist/assets` into your app's `public` directory. Then you can point the base path to that folder instead.
+
+Now you can start using components!
+
+## Usage
+
+### Importing Components
+
+Every Shoelace component is available to import as a React component. Note that we're importing the `<SlButton>` _React component_ instead of the `<sl-button>` _custom element_ in the example below.
+
+```jsx
+import { SlButton } from '@shoelace-style/shoelace/dist/react';
+
+const MyComponent = () => (
+  <SlButton variant="primary">
+    Click me
+  </SlButton>
+);
+
+export default MyComponent;
+```
+
+You can find a copy + paste import for each component in the "importing" section of its documentation.
+
+### Event Handling
+
+Many Shoelace components emit [custom events](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent). For example, the [input component](/components/input) emits the `sl-input` event when it receives input. In React, you can listen for the event using `onSlInput`.
+
+Here's how you can bind the input's value to a state variable.
+
+```jsx
+import { useState } from 'react';
+import { SlInput } from '@shoelace-style/shoelace/dist/react';
+
+function MyComponent() {
+  const [value, setValue] = useState('');
+
+  return (
+    <SlInput 
+      value={value} 
+      onSlInput={event => setValue(event.target.value)} 
+    />
+  )
+};
+
+export default MyComponent;
+```
+
+If you're using TypeScript, it's important to note that `event.target` will be a reference to the underlying custom element. You can use `(event.target as any).value` as a quick fix, or you can strongly type the event target as shown below.
+
+```tsx
+import { useState } from 'react';
+import { SlInput } from '@shoelace-style/shoelace/dist/react';
+import type SlInputElement from '@shoelace-style/shoelace/dist/components/input/input';
+
+function MyComponent() {
+  const [value, setValue] = useState('');
+
+  return (
+    <SlInput 
+      value={value} 
+      onSlInput={event => setValue((event.target as SlInputElement).value)} 
+    />
+  )
+};
+
+export default MyComponent;
+```
+
+## Testing with Jest
+
+Testing with web components can be challenging if your test environment runs in a Node environment (i.e. it doesn't run in a real browser). Fortunately, [Jest](https://jestjs.io/) has made a number of strides to support web components and provide additional browser APIs. However, it's still not a complete replication of a browser environment.
+
+Here are some tips that will help smooth things over if you're having trouble with Jest + Shoelace.
+
+?> If you're looking for a fast, modern testing alternative, consider [Web Test Runner](https://modern-web.dev/docs/test-runner/overview/).
+
+### Upgrade Jest
+
+Jest underwent a major revamp and received support for web components in [version 26.5.0](https://github.com/facebook/jest/blob/main/CHANGELOG.md#2650) when it introduced [JSDOM 16.2.0](https://github.com/jsdom/jsdom/blob/master/Changelog.md#1620). This release also included a number of mocks for built-in browser functions such as `MutationObserver`, `document.createRange`, and others.
+
+If you're using [Create React App](https://reactjs.org/docs/create-a-new-react-app.html#create-react-app), you can update `react-scripts` which will also update Jest.
+
+```
+npm install react-scripts@latest
+```
+
+### Mock Missing APIs
+
+Some components use `window.matchMedia`, but this function isn't supported by JSDOM so you'll need to mock it yourself.
+
+In `src/setupTests.js`, add the following.
+
+```js
+Object.defineProperty(window, 'matchMedia', {
+  writable: true,
+  value: jest.fn().mockImplementation(query => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: jest.fn(), // deprecated
+    removeListener: jest.fn(), // deprecated
+    addEventListener: jest.fn(),
+    removeEventListener: jest.fn(),
+    dispatchEvent: jest.fn(),
+  })),
+});
+```
+
+For more details, refer to Jest's [manual mocking](https://jestjs.io/docs/manual-mocks#mocking-methods-which-are-not-implemented-in-jsdom) documentation.
+
+### Transform ES Modules
+
+ES Modules are a [well-supported browser standard](https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/). This is how Shoelace is distributed, but most React apps expect CommonJS. As a result, you'll probably run into the following error.
+
+```
+Error: Unable to import outside of a module
+```
+
+To fix this, add the following to your `package.json` which tells the transpiler to process Shoelace modules.
+
+```js
+{
+  "jest": {
+    "transformIgnorePatterns": ["node_modules/?!(@shoelace)"]
+  }
+}
+```
+
+These instructions are for apps created via Create React App. If you're using Jest directly, you can add `transformIgnorePatterns` directly into `jest.config.js`.
+
+For more details, refer to Jest's [`transformIgnorePatterns` customization](https://jestjs.io/docs/tutorial-react-native#transformignorepatterns-customization) documentation.
+
+?> Are you using Shoelace with React? [Help us improve this page!](https://github.com/shoelace-style/shoelace/blob/next/docs/frameworks/react.md)

docs/frameworks/vue.md

@@ -0,0 +1,92 @@
+# Vue
+
+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).
+
+## 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 { createApp } from 'vue';
+import App from './App.vue';
+
+const app = createApp(App);
+
+app.config.compilerOptions.isCustomElement = tag => tag.startsWith('sl-');
+
+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">
+
+<!-- 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

@@ -40,26 +40,24 @@ 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) {
-    background: rgb(var(--sl-color-neutral-0));
+    background: var(--sl-color-neutral-0);
     border: solid 1px tomato;
   }
 
   .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 {
-    box-shadow: 0 0 0 3px rgba(255, 99, 71, .33);
+  .tomato-button::part(base):focus-visible {
+    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
 

docs/getting-started/form-controls.md

@@ -0,0 +1,336 @@
+# 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.
+
+?> If you're using an older browser that doesn't support the `formdata` event, a lightweight polyfill will be automatically applied to ensure forms submit as expected.
+
+## Form 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'] }`.
+
+## 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 Shoelace form controls. You can activate it using attributes such as `required`, `pattern`, `minlength`, and `maxlength`. Shoelace implements many of the same attributes as native form controls, but check each form control's documentation for a list of all supported properties.
+
+As the user interacts with a form control, its `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 surrounding `<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
+<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="submit" variant="primary">Submit</sl-button>
+</form>
+
+<script>
+  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>
+</form>
+
+<script>
+  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 variant="email" label="Email" placeholder="you@example.com" required></sl-input>
+  <br>
+  <sl-input variant="url" label="URL" placeholder="https://example.com/" required></sl-input>
+  <br>
+  <sl-button type="submit" variant="primary">Submit</sl-button>
+</form>
+
+<script>
+  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 variant="email" label="Email" placeholder="you@example.com" required />
+      <br />
+      <SlInput variant="url" label="URL" placeholder="https://example.com/" required />
+      <br />
+      <SlButton type="submit" variant="primary">Submit</SlButton>
+    </form>
+  );
+};
+```
+
+### 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
+<form class="input-validation-custom">
+  <sl-input label="Type 'shoelace'" required></sl-input>
+  <br>
+  <sl-button type="submit" variant="primary">Submit</sl-button>
+</form>
+
+<script>
+  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 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
+<form novalidate>
+  <sl-input class="invalid"></sl-input>
+</form>
+
+<style>
+  sl-input.invalid {
+    ...
+  }
+</style>
+```

docs/getting-started/installation.md

@@ -2,7 +2,9 @@
 
 You can use Shoelace via CDN or by installing it locally. You can also [cherry pick](#cherry-picking) individual components for faster load times.
 
-## CDN Installation (Recommended)
+If you're using a framework, make sure to check out the pages for [React](/frameworks/react), [Vue](/frameworks/vue), and [Angular](/frameworks/angular).
+
+## CDN Installation (Easiest)
 
 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.
 
@@ -11,9 +13,11 @@ The easiest way to install Shoelace is with the CDN. Just add the following tags
 <script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/shoelace.js"></script>
 ```
 
+?> If you're only using a handful of components, it will be more efficient to [cherry pick](#cherry-picking) the ones you need.
+
 ### Dark Theme
 
-If you prefer to use the dark theme instead, use this. Note the `sl-theme-dark` class on the `<html>` element. [Learn more about the Dark Theme.](/getting-started/themes#dark-theme)
+If you prefer to use the [dark theme](/getting-started/themes#dark-theme) instead, use this code and add `<html class="sl-theme-dark">` to the page.
 
 ```html
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/dist/themes/dark.css">
@@ -63,13 +67,13 @@ However, if you're [cherry picking](#cherry-picking) or [bundling](#bundling) Sh
 
 ```html
 <!-- Option 1: the data-shoelace attribute -->
-<script src="bundle.js" data-shoelace="/path/to/shoelace"></script>
+<script src="bundle.js" data-shoelace="/path/to/shoelace/dist"></script>
 
 <!-- Option 2: the setBasePath() method -->
 <script src="bundle.js"></script>
 <script type="module">
   import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path.js';
-  setBasePath('/path/to/shoelace');
+  setBasePath('/path/to/shoelace/dist');
 </script>
 ```
 
@@ -77,16 +81,16 @@ However, if you're [cherry picking](#cherry-picking) or [bundling](#bundling) Sh
 
 ## Cherry Picking
 
-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, but may result in longer load times in production. To improve this, you can cherry pick the components you need.
+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.
 
 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="@shoelace-style/shoelace/dist/themes/light.css">
+<link rel="stylesheet" href="/path/to/shoelace/dist/themes/light.css">
 
-<script type="module" data-shoelace="/path/to/shoelace">
+<script type="module" data-shoelace="/path/to/shoelace/dist">
   import '@shoelace-style/shoelace/dist/components/button/button.js';
 
   // <sl-button> is ready to use!
@@ -125,7 +129,7 @@ import '@shoelace-style/shoelace/dist/components/rating/rating.js';
 import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path.js';
 
 // Set the base path to the folder you copied Shoelace's assets to
-setBasePath('/dist/shoelace');
+setBasePath('/path/to/shoelace/dist');
 
 // <sl-button>, <sl-icon>, <sl-input>, and <sl-rating> are ready to use!
 ```

docs/getting-started/localization.md

@@ -0,0 +1,140 @@
+# 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.
+
+```html
+<html lang="es">
+  <head>
+    <script type="module" src="/path/to/shoelace/dist/translations/es.js"></script>
+  </head>
+
+  <body>
+    ...
+  </body>
+</html>
+```
+
+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
+
+The location of translations depends on how you're consuming Shoelace.
+
+- If you're using the CDN, [import them from the CDN](https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace?path=dist%2Ftranslations)
+- If you're using a bundler, import them from `@shoelace-style/shoelace/dist/translations/[lang].js`
+
+You do not need to load translations up front. You can import them dynamically even after updating the `lang` attribute. Once a translation is registered, localized components will update automatically.
+
+```js
+// Same as setting <html lang="de">
+document.documentElement.lang = 'de';
+
+// Import the translation
+import('/path/to/shoelace/dist/translations/de.js');
+```
+
+### Translation Resolution
+
+The locale set by `<html lang="...">` is the default locale for the document. If a country code is provided, e.g. `es-PE` for Peruvian Spanish, the localization library will resolve it like this:
+
+1. Look for `es-PE`
+2. Look for `es`
+3. Fall back to `en`
+
+Shoelace uses English as a fallback to provide a better experience than rendering nothing or throwing an error.
+
+### Submitting New Translations or Improvements
+
+To contribute new translations or improvements to existing translations, please submit a pull request on GitHub. Translations are located in [`src/translations`](https://github.com/shoelace-style/shoelace/blob/next/src/translations) and can be edited directly on GitHub if you don't want to clone the repo locally.
+
+Regional translations are welcome! For example, if a German translation (`de`) exists it's perfectly acceptable to submit a German (Switzerland) (`de-CH`) translation.
+
+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).
+
+## 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.
+
+```html
+<html lang="es">
+  ...
+
+  <body>
+    <sl-button><!-- Spanish --></sl-button>
+    <sl-button lang="ru"><!-- Russian --></sl-button>
+  </body>
+</html>
+```
+
+For performance reasons, the `lang` attribute must be on the component itself, not on an ancestor element.
+
+```html
+<html lang="es">
+  ...
+
+  <body>
+    <div lang="ru">
+      <sl-button><!-- still in Spanish --></sl-button>
+    </div>
+  </body>
+</html>
+```
+
+This limitation exists because there's no efficient way to determine the current locale of a given element in a DOM tree. I consider this a gap in the platform and [I've proposed a couple properties](https://github.com/whatwg/html/issues/7039) to make this possible.
+
+## Creating Your Own Translations
+
+You can provide your own translations if you have specific needs or if you don't want to wait for a translation to land upstream. The easiest way to do this is to copy `src/translations/en.ts` into your own project and translate the terms inside. When your translation is done, you can import it and use it just like a built-in translation.
+
+Let's create a Spanish translation as an example. The following assumes you're using TypeScript, but you can also create translations with regular JavaScript.
+
+```js
+import { registerTranslation } from '@shoelace-style/shoelace/dist/utilities/localize';
+import type { Translation } from '@shoelace-style/shoelace/dist/utilities/localize';
+
+const translation: Translation = {
+  $code: 'es',
+  $name: 'Español',
+  $dir: 'ltr',
+
+  term1: '...',
+  term2: '...',
+  ...
+};
+
+registerTranslation(translation);
+
+export default translation;
+```
+
+Once your translation has been compiled to JavaScript, import it and activate it like this.
+
+```html
+<html lang="es">
+  <head>
+    <script type="module" src="/path/to/es.js"></script>
+  </head>
+
+  <body>
+    ...
+  </body>
+</html>
+```
+
+?> If your translation isn't working, make sure you're using the same localize module when importing `registerTranslation`. If you're using a different module, your translation won't be recognized.

docs/getting-started/overview.md

@@ -9,7 +9,8 @@
 - Fully customizable with CSS 🎨
 - Includes a dark theme 🌛
 - Built with accessibility in mind ♿️
-- First-party [React wrappers](/getting-started/usage#react)
+- First-class [React support](/frameworks/react) ⚛️
+- Built-in localization 💬
 - Open source 😸
 
 Designed in New Hampshire by [Cory LaViska](https://twitter.com/claviska).
@@ -37,11 +38,12 @@ Add the following code to your page.
 
 Now you have access to all of Shoelace's components! Try adding a button:
 
-```html
+```html preview expanded
 <sl-button>Click me</sl-button>
 ```
 
-See the [installation instructions](getting-started/installation) for more details and other ways to install Shoelace.
+?> 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?
 
@@ -61,13 +63,15 @@ This is the technology that Shoelace is built on.
 
 ## What Problem Does This Solve?
 
-Shoelace provides a collection of professionally designed, every day UI components built on a framework-agnostic technology. Why spend hundreds of hours (or more) building a design system from scratch? Why make a component library that only works with one framework?
+Shoelace provides a collection of professionally designed, highly customizable UI components built on a framework agnostic technology. Why spend hundreds of hours (or more) building a design system from scratch? Why make a component library that only works with one framework?
 
 With Shoelace, you can:
 
 - Start building things faster (no need to roll your own buttons)
-- Build multiple apps with different frameworks that all share the same UI
-- Skip having to learn a new component library every time you switch frameworks
+- Build multiple apps with different frameworks that all share the same UI components
+- Fully customize components to match your existing designs
+- 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.
 
@@ -98,15 +102,15 @@ Designing, developing, and supporting this library requires a lot of time, effor
 👇 Your support is very much appreciated! 👇
 
 <sl-button class="repo-button repo-button--sponsor" href="https://github.com/sponsors/claviska" target="_blank">
-  <sl-icon name="heart"></sl-icon> Become a sponsor
+  <sl-icon slot="prefix" name="heart"></sl-icon> Become a sponsor
 </sl-button>
 
 <sl-button class="repo-button repo-button--github" href="https://github.com/shoelace-style/shoelace/stargazers" target="_blank">
-  <sl-icon name="github"></sl-icon> <span class="github-star-count">Star</span>
+  <sl-icon slot="prefix" name="github"></sl-icon> <span class="github-star-count">Star</span>
 </sl-button>
 
 <sl-button class="repo-button repo-button--twitter" href="https://twitter.com/shoelace_style" target="_blank">
-  <sl-icon name="twitter"></sl-icon> Follow
+  <sl-icon slot="prefix" name="twitter"></sl-icon> Follow
 </sl-button>
 
 ## Attribution
@@ -117,7 +121,7 @@ Special thanks to the following projects and individuals that help make Shoelace
 - 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 derived from [Tailwind](https://tailwindcss.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/)

docs/getting-started/themes.md

@@ -1,16 +1,16 @@
 # Themes
 
-Shoelace is designed to be highly customizable through pure CSS. Out of the box, you can choose from a light or dark theme. Alternatively, you can design your own theme from scratch.
+Shoelace is designed to be highly customizable through pure CSS. Out of the box, you can choose from a light or dark theme. Alternatively, you can design your own theme.
 
 A theme is nothing more than a stylesheet that uses the Shoelace API to define design tokens and apply custom styles to components. To create a theme, you will need a decent understanding of CSS, including [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) and the [`::part` selector](https://developer.mozilla.org/en-US/docs/Web/CSS/::part).
 
-For developers, built-in themes are also available as JavaScript modules that export [Lit CSSResult](https://lit.dev/docs/api/styles/#CSSResult) objects. You can find them in `dist/themes/*.styles.js`.
+?> For component developers, built-in themes are also available as JavaScript modules that export [Lit CSSResult](https://lit.dev/docs/api/styles/#CSSResult) objects. You can find them in `dist/themes/*.styles.js`.
 
 ## 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 the `sl-theme-purple-power` class. 
+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` 
 
-Every selector 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.
+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.
 
 ```css
 :host,
@@ -21,7 +21,7 @@ Every selector must be scoped to the theme's class to ensure interoperability wi
 
 ### Activating Themes
 
-To activate a theme, import it and apply the theme's class to the `<html>` element. This example imports and activates the dark theme, or "dark mode."
+To activate a theme, import it and apply the theme's class to the `<html>` element. This example imports and activates the built-in dark theme.
 
 ```html
 <html class="sl-theme-dark">
@@ -58,13 +58,15 @@ You can activate themes on various containers throughout the page. This example
 </html>
 ```
 
+It's for this reason that themes must be scoped to specific classes.
+
 ## Creating Themes
 
 There are two ways to create themes. The easiest way is to customize a built-in theme. The advanced way is to create a new theme from scratch. Which method you choose depends on your project's requirements and the amount of effort you're willing to commit to.
 
 ### Customizing a Built-in Theme
 
-The easiest way to customize Shoelace is to override one of the built-in themes. You can do this by importing the light or dark theme as-is, then creating a separate stylesheet that overrides the [design tokens](/getting-started/customizing#design-tokens) and adds [component styles](/getting-started/customizing#component-parts) to your liking. You must import your theme _after_ the built-in theme.
+The easiest way to customize Shoelace is to override one of the built-in themes. You can do this by importing the light or dark theme as-is, then creating a separate stylesheet that overrides [design tokens](/getting-started/customizing#design-tokens) and adds [component styles](/getting-started/customizing#component-parts) to your liking. You must import your theme _after_ the built-in theme.
 
 If you're customizing the light theme, you should scope your styles to the following selectors.
 
@@ -87,7 +89,7 @@ If you're customizing the dark theme, you should scope your styles to the follow
 
 By customizing a built-in theme, you'll maintain a smaller stylesheet containing only the changes you've made. Contrast this to [creating a new theme](#creating-a-new-theme), where you need to explicitly define every design token required by the library. This approach is more "future-proof," as new design tokens that emerge in subsequent versions of Shoelace will be accounted for by the built-in theme.
 
-While this may be easier to maintain, the drawback is that your theme modifies a built-in theme and thus can't be activated independently.
+While this approach is easier to maintain, the drawback is that your theme can't be activated independently — it's tied to the built-in theme you're extending.
 
 ### Creating a New Theme
 
@@ -108,9 +110,9 @@ You will, however, need to maintain your theme more carefully, as new versions o
 
 ## Dark Theme
 
-The built-in dark theme uses an inverted + shifted color scale so, if you're using design tokens as intended, you'll get a decent dark mode for free. While this isn't the same as a professionally curated dark theme, it provides an excellent baseline for one and you're encouraged to customize it depending on your needs.
+The built-in dark theme uses an inverted color scale so, if you're using design tokens as intended, you'll get dark mode for free. While this isn't the same as a professionally curated dark theme, it provides an excellent baseline for one and you're encouraged to customize it depending on your needs.
 
-This was achieved by taking the light theme's [color tokens](/tokens/color) and "flipping" the scale so 100 becomes 900, 200 becomes 800, 300 becomes 700, etc. Next, the luminance of each primitive was increased slightly to avoid true black, a color that is typically undesirable in dark themes. The result is a custom palette that complements the light theme well and makes it easy to offer light and dark variations with minimal effort.
+The dark theme works by taking the light theme's [color tokens](/tokens/color) and "flipping" the scale so 100 becomes 900, 200 becomes 800, 300 becomes 700, etc. Next, the luminance of each primitive was fine-tuned to avoid true black, which is often undesirable in dark themes, and provide a richer experience. The result is a custom dark palette that complements the light theme and makes it easy to offer light and dark modes with minimal effort.
 
 To install the dark theme, add the following to the `<head>` section of your page.
 

docs/getting-started/usage.md

@@ -1,10 +1,10 @@
 # Usage
 
-Shoelace components are just regular HTML elements, or "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.
+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.
 
-## Web Component Basics
+If you're new to custom elements, often referred to as "web components," this section will familiarize you with how to use them. 
 
-### Properties
+## 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.
 
@@ -31,7 +31,7 @@ In rare cases, a property may require an array, an object, or a function. For ex
 
 Refer to a component's documentation for a complete list of its properties.
 
-### Events
+## Events
 
 You can listen for standard events such as `click`, `mouseover`, etc. as you normally would. In addition, some components emit custom events. These work the same way as standard events, but are prefixed with `sl-` to prevent collisions with standard events and other libraries.
 
@@ -48,7 +48,7 @@ You can listen for standard events such as `click`, `mouseover`, etc. as you nor
 
 Refer to a component's documentation for a complete list of its custom events.
 
-### Methods
+## Methods
 
 Some components have methods you can call to trigger various behaviors. For example, you can set focus on a Shoelace input using the `focus()` method.
 
@@ -63,7 +63,7 @@ Some components have methods you can call to trigger various behaviors. For exam
 
 Refer to a component's documentation for a complete list of its methods and their arguments.
 
-### Slots
+## Slots
 
 Many components use slots to accept content inside of them. The most common slot is the _default_ slot, which includes any content inside the component that doesn't have a `slot` attribute.
 
@@ -86,7 +86,7 @@ The location of a named slot doesn't matter. You can put it anywhere inside the
 
 Refer to a component's documentation for a complete list of available slots.
 
-### Don't Use Self-closing Tags
+## Don't Use Self-closing Tags
 
 Custom elements cannot have self-closing tags. Similar to `<script>` and `<textarea>`, you must always include the full closing tag.
 
@@ -98,7 +98,7 @@ Custom elements cannot have self-closing tags. Similar to `<script>` and `<texta
 <sl-input></sl-input>
 ```
 
-### Differences from Native Elements
+## Differences from Native Elements
 
 You might expect similarly named elements to share the same API as native HTML elements. This is not always the case. Shoelace components **are not** designed to be one-to-one replacements for their HTML counterparts.
 
@@ -106,6 +106,49 @@ 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: .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>
+```
+
 ## Code Completion
 
 ### VS Code
@@ -128,123 +171,3 @@ If `settings.json` already exists, simply add the above line to the root of the
 ### Other Editors
 
 Most popular editors support custom code completion with a bit of configuration. Please [submit a feature request](https://github.com/shoelace-style/shoelace/issues/new/choose) for your editor of choice. PRs are also welcome!
-
-## React
-
-React [doesn't play nice](https://custom-elements-everywhere.com/#react) with custom elements — it's a bit finicky about props.
-
-> React passes all data to Custom Elements in the form of HTML attributes. For primitive data this is fine, but the system breaks down when passing rich data, like objects or arrays. In these instances you end up with stringified values like `some-attr="[object Object]"` which can't actually be used.
-
-Event handling can also be cumbersome.
-
-> Because React implements its own synthetic event system, it cannot listen for DOM events coming from Custom Elements without the use of a workaround. Developers will need to reference their Custom Elements using a ref and manually attach event listeners with addEventListener. This makes working with Custom Elements cumbersome.
-
-Fortunately, there's a package called [@shoelace-style/react](https://www.npmjs.com/package/@shoelace-style/react) that will let you use Shoelace components as if they were React components. You can install it using this command.
-
-```bash
-npm install @shoelace-style/react
-```
-
-Include the default theme and any components you want to use in your app.
-
-```jsx
-import '@shoelace-style/shoelace/dist/themes/light.css';
-
-import SlButton from '@shoelace-style/react/dist/button';
-
-// ...
-
-const MyComponent = (props) => {
-  return (
-    <SlButton type="primary">
-      Click me
-    </SlButton>
-  )
-};
-```
-
-## Vue
-
-Vue [plays nice](https://custom-elements-everywhere.com/#vue) with custom elements. You just have to tell it to ignore Shoelace components. This is pretty easy because they all start with `sl-`.
-
-```js
-import { createApp } from 'vue';
-import App from './App.vue';
-
-const app = createApp(App);
-
-app.config.compilerOptions.isCustomElement = tag => tag.startsWith('sl-');
-
-app.mount('#app');
-```
-
-### 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">
-
-<!-- This works, but it's a bit longer -->
-<sl-input :value="name" @input="name = $event.target.value">
-```
-
-If that's too verbose, you can use a custom directive instead.
-
-### Using a Custom Directive
-
-You can use [this utility](https://www.npmjs.com/package/@shoelace-style/vue-sl-model) to add 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">
-```
-
-## Angular
-
-Angular [plays nice](https://custom-elements-everywhere.com/#angular) with custom elements. Just make sure to apply the custom elements schema as shown below.
-
-```js
-import { BrowserModule } from '@angular/platform-browser';
-import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
-
-import { AppComponent } from './app.component';
-
-@NgModule({
-  declarations: [AppComponent],
-  imports: [BrowserModule],
-  providers: [],
-  bootstrap: [AppComponent],
-  schemas: [CUSTOM_ELEMENTS_SCHEMA]
-})
-export class AppModule {}
-```

docs/index.html

@@ -8,10 +8,7 @@
       name="description"
       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, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"
-    />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
     <meta name="custom-elements-manifest" content="dist/custom-elements.json" />
     <meta property="og:title" content="Shoelace" />
     <meta
@@ -44,7 +41,7 @@
     <link rel="stylesheet" href="/dist/themes/dark.css" />
     <script type="module" src="/dist/shoelace.js"></script>
   </head>
-  <body>
+  <body data-shoelace="/dist">
     <div id="app"></div>
     <script>
       // Set the initial theme to prevent flashing
@@ -81,15 +78,16 @@
           crossChapterText: false
         },
         routerMode: 'history',
-        themeColor: 'rgb(var(--sl-color-primary-500))'
+        themeColor: 'var(--sl-color-primary-500)'
       };
     </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.19.0/components/prism-bash.min.js"></script>
-    <script src="https://cdn.jsdelivr.net/npm/prismjs@1.19.0/components/prism-jsx.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/prismjs@1.25.0/components/prism-bash.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/prismjs@1.25.0/components/prism-jsx.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/prismjs@1.25.0/components/prism-tsx.min.js"></script>
     <script src="/assets/plugins/code-block/code-block.js"></script>
     <script src="/assets/plugins/metadata/metadata.js"></script>
     <script src="/assets/plugins/scroll-position/scroll-position.js"></script>

docs/resources/accessibility.md

@@ -0,0 +1,18 @@
+# Accessibility Commitment
+
+Shoelace recognizes the need for all users, regardless of ability and device, to have undeterred access to the websites and applications that are created with it. This is an important goal of the project.
+
+Oftentimes, people will ask “is Shoelace accessible?” I’m reluctant to answer because accessibility isn’t binary — there’s no simple “yes” or “no” response to provide. What seems accessible to a sighted user might be completely inaccessible to a non-sighted user. And even if you optimize for various screen readers, you still have to account for low-level vision, color blindness, hearing impairments, mobility impairments, and more.
+
+Accessibility is something you have to continuously strive for. No individual contributor — or perhaps even an entire team — can claim their software is 100% accessible because of the sheer diversity of abilities, devices, assistive technologies, and individual use cases.
+
+Furthermore, accessibility doesn’t stop at the component level. Using accessible building blocks doesn’t magically make the rest of your webpage or application compliant. There is no library or overlay that will make your software “fully accessible” without putting in the effort. It’s also worth noting that web components are still somewhat bleeding edge, so browsers, assistive devices, and [even specifications](https://wicg.github.io/aom/spec/) are still evolving to help improve accessibility on the web platform.
+
+My commitment to Shoelace users is this: Everything I develop will be built with accessibility in mind. I will test and improve every component to the best of my ability and knowledge. I will work around upstream issues, such as browser bugs and limitations, to the best of my ability and within reason.
+
+I’m fully aware that I may not get it right every time for every user, so I invite the community to participate in this ongoing effort by submitting [issues](https://github.com/shoelace-style/shoelace/issues?q=is%3Aissue+is%3Aopen+label%3Aa11y), [pull requests](https://github.com/shoelace-style/shoelace/pulls?q=is%3Aopen+is%3Apr+label%3Aa11y), and [discussions](https://github.com/shoelace-style/shoelace/discussions). Many accessibility improvements have already been made thanks to contributors submitting code, feedback, and suggestions.
+
+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_

docs/resources/changelog.md

@@ -1,18 +1,143 @@
 # 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._ 🐛
 
-## Next
+## 2.0.0-beta.66
 
-- Added experimental `<sl-context-menu>` component
+- Fixes a bug that prevented types from being shipped
+
+## 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` CSS 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 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
+
+- 🚨 BREAKING: changed the `locale` attribute to `lang` in `<sl-format-bytes>`, `<sl-format-date>`, `<sl-format-number>`, and `<sl-relative-time>` to be consistent with how localization is handled
+- Added localization support including translations for English, German, German (Switzerland), Spanish, French, Hebrew, Japanese, Dutch, Polish, Portuguese, and Russian translations [#419](https://github.com/shoelace-style/shoelace/issues/419)
+- CodePen examples will now open in light or dark depending on your current preference
+- Fixed a bug where tag names weren't being generated in `vscode.html-custom-data.json` [#593](https://github.com/shoelace-style/shoelace/pull/593)
+- Fixed a bug in `<sl-tooltip>` where the tooltip wouldn't reposition when content changed
+- Fixed a bug in `<sl-select>` where focusing on a filled control showed the wrong focus ring
+- Fixed a bug where setting `value` initially on `<sl-color-picker>` didn't work in React [#602](https://github.com/shoelace-style/shoelace/issues/602)
+- Updated filled inputs to have the same appearance when focused
+- Updated `color` dependency from 3.1.3 to 4.0.2
+- Updated `<sl-format-bytes>`, `<sl-format-date>`, `<sl-format-number>`, and `<sl-relative-time>` to work like other localized components
+- Upgraded the status of `<sl-qr-code>` from experimental to stable
+- Updated to Bootstrap Icons to 1.7.2
+- Upgraded color to 4.1.0
+
+## 2.0.0-beta.61
+
+This release improves the dark theme by shifting luminance in both directions, slightly condensing the spectrum. This results in richer colors in dark mode. It also reduces theme stylesheet sizes by eliminating superfluous gray palette variations.
+
+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.
+
+If you're using color tokens in your own stylesheet, simply remove the `rgb()` to update to this version.
+
+```css
+.your-styles {
+  /* change this */
+  color: rgb(var(--sl-color-primary-500));
+
+  /* to this */
+  color: var(--sl-color-primary-500);
+}
+```
+
+Thank you for your help and patience with testing Shoelace. I promise, we're not far from a stable release!
+
+- 🚨 BREAKING: removed blue gray, cool gray, true gray, and warm gray color palettes
+- 🚨 BREAKING: removed `--sl-focus-ring-color`, and `--sl-focus-ring-alpha` (use `--sl-focus-ring` instead)
+- 🚨 BREAKING: removed `--sl-surface-base` and `--sl-surface-base-alt` tokens (use the neutral palette instead)
+- Added experimental `<sl-visually-hidden>` component
+- Added `clear-icon` slot to `<sl-select>` [#591](https://github.com/shoelace-style/shoelace/issues/591)
+- Fixed a bug in `<sl-progress-bar>` where the label would show in the default slot
+- Improved the dark theme palette so colors are bolder and don't appear washed out
+- Improved a11y of `<sl-avatar>` by representing it as an image with an `alt` [#579](https://github.com/shoelace-style/shoelace/issues/579)
+- 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)
+- 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>`
+- Updated to Bootstrap Icons to 1.7.1
+- Upgraded the status of `<sl-mutation-observer>` from experimental to stable
+
+## 2.0.0-beta.60
+
+- Added React examples and CodePen links to all components
+- Changed the `attr` in experimental `<sl-mutation-observer>` to require `"*"` instead of `""` to target all attributes
+- Fixed a bug in `<sl-progress-bar>` where the `label` attribute didn't set the label
+- Fixed a bug in `<sl-rating>` that caused disabled and readonly controls to transition on hover
+- The `panel` property of `<sl-tab>` is now reflected
+- The `name` property of `<sl-tab-panel>` is now reflected
+
+## 2.0.0-beta.59
+
+- Added React wrappers as first-class citizens
 - Added eye dropper to `<sl-color-picker>` when the browser supports the [EyeDropper API](https://wicg.github.io/eyedropper-api/)
 - Fixed a bug in `<sl-button-group>` where buttons groups with only one button would have an incorrect border radius
 - Improved the `<sl-color-picker>` trigger's border in dark mode
-- Refactored positioning logic in `<sl-dropdown>` so Popper is only active when the menu is open
+- Switched clearable icon from `x-circle` to `x-circle-fill` to make it easier to recognize
+- Updated to Bootstrap Icons to 1.7.0
 - Updated to Lit 2.0.2
 
 ## 2.0.0-beta.58
@@ -58,11 +183,11 @@ Shoelace doesn't have a lot of dependencies, but this release unbundles most of
 ## 2.0.0-beta.53
 
 - 🚨 BREAKING: removed `<sl-menu-divider>` (use `<sl-divider>` instead)
-- 🚨 BREAKING: removed `percentage` attribute from `<sl-progress-bar>` and `<sl-progress-ring>` (use `value`) instead
+- 🚨 BREAKING: removed `percentage` attribute from `<sl-progress-bar>` and `<sl-progress-ring>` (use `value` instead)
 - 🚨 BREAKING: switched the default `type` of `<sl-tag>` from `primary` to `neutral`
 - Added the experimental `<sl-mutation-observer>` component
 - Added the `<sl-divider>` component
-- Added `--sl-surface-base` and `--sl-surface-base-alt` as early surface tokens to improve the appearance of alert, card, and panels in dark mode
+- Added `--sl-color-neutral-0` and `--sl-color-neutral-50` as early surface tokens to improve the appearance of alert, card, and panels in dark mode
 - Added the `--sl-panel-border-width` design token
 - Added missing background color to `<sl-details>`
 - Added the `--padding` custom property to `<sl-tab-panel>`
@@ -138,14 +263,14 @@ 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 {
   /* rgb() is required now */
-  color: rgb(var(--sl-color-neutral-500));
+  color: var(--sl-color-neutral-500);
 }
 ```
 
@@ -195,7 +320,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
 
@@ -232,7 +357,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)
@@ -256,7 +381,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)
@@ -275,7 +400,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)
@@ -486,7 +611,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
@@ -557,7 +682,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
@@ -595,7 +720,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,16 +27,16 @@ 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>
 
 ## Stack Overflow
 
-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 or actively monitored by the Shoelace author.
+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>

docs/resources/contributing.md

@@ -85,11 +85,17 @@ npm install
 Once you've cloned the repo, run the following command to spin up the Shoelace dev server.
 
 ```bash
-npm start
+npm run start
 ```
 
 After the initial build, a browser will open automatically to a local version of the docs. The documentation is powered by Docsify, which uses raw markdown files to generate pages on the fly.
 
+### Cloud-based Development
+
+Alternatively, you can use [Gitpod](https://www.gitpod.io/) to setup a dev environment in the cloud using only your browser.
+
+[![Open in Gitpod](../assets/images/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/shoelace-style/shoelace)
+
 ### Creating New Components
 
 To scaffold a new component, run the following command, replacing `sl-tag-name` with the desired tag name.
@@ -104,7 +110,7 @@ This will generate a source file, a stylesheet, and a docs page for you. When yo
 
 Component development occurs _within_ the local docs site. I've found that offering common variations _in the docs_ is more beneficial for users than segmenting demos and code examples into separate tools such as Storybook. This encourages more thorough documentation, streamlines development for maintainers, and simplifies how the project is built. It also reduces installation and startup times significantly.
 
-There is currently no hot module reloading (HMR), as browsers don't provide a way to unregister custom elements. However, most changes to the source will reload the browser automatically. 
+There is currently no hot module reloading (HMR), as browsers don't provide a way to unregister custom elements. However, most changes to the source will reload the browser automatically.
 
 For more information about running and building the project locally, refer to `README.md` in the project's root.
 
@@ -113,7 +119,7 @@ For more information about running and building the project locally, refer to `R
 Shoelace uses [Web Test Runner](https://modern-web.dev/guides/test-runner/getting-started/) for testing. To launch the test runner during development, open a terminal and launch the dev server.
 
 ```bash
-npm start
+npm run start
 ```
 
 In a second terminal window, launch the test runner.
@@ -124,13 +130,20 @@ npm run test:watch
 
 Follow the on-screen instructions to work with the test runner. Tests will automatically re-run as you make changes.
 
-To run tests only once, make sure to build the project first.
+To run all tests only once:
 
 ```bash
-npm run build
 npm run test
 ```
 
+To run just one test file:
+
+If the test file is `src/components/breadcrumb-item.test.ts`, then `<nameOfTestFile>` would be `breadcrumb-item`.
+
+```bash
+npm run test -- --group <nameOfTestFile>
+```
+
 ## Best Practices
 
 The following is a non-exhaustive list of conventions, patterns, and best practices we try to follow. As a contributor, we ask that you make a good faith effort to follow them as well. This ensures consistency and maintainability throughout the project.
@@ -171,7 +184,7 @@ Components should be composable, meaning you can easily reuse them with and with
 
 The `<sl-select>` component, for example, makes use of the dropdown, input, menu, and menu item components. Because it's offloading most of its functionality and styles to lower-level components, the select component remains lightweight and its appearance is consistent with other form controls and menus.
 
-### Component Stucture
+### Component Structure
 
 All components have a host element, which is a reference to the `<sl-*>` element itself. Make sure to always set the host element's `display` property to the appropriate value depending on your needs, as the default is `inline` per the custom element spec.
 
@@ -215,8 +228,8 @@ To expose custom properties as part of a component's API, scope them to the `:ho
 
 ```css
 :host {
-  --color: rgb(var(--sl-color-primary-500));
-  --background-color: rgb(var(--sl-color-neutral-100));
+  --color: var(--sl-color-primary-500);
+  --background-color: var(--sl-color-neutral-100);
 }
 ```
 
@@ -225,7 +238,7 @@ Then use the following syntax for comments so they appear in the generated docs.
 ```js
 /**
  * @cssproperty --color: The component's text color.
- * @cssproperty --background-color: The component's background color. 
+ * @cssproperty --background-color: The component's background color.
  */
 @customElement('sl-example')
 export default class SlExample {
@@ -249,31 +262,13 @@ Parts let you target a specific element inside the component's shadow DOM but, b
 
 This convention can be relaxed when the developer experience is greatly improved by not following these suggestions.
 
-### Design Token Color Values
-
-All design tokens that implement a color value must do so in the following `R G B` format for consistency.
-
-```css
-:root {
-  --sl-color-sky-500: 14 165 233;
-}
-```
-
-This format requires the consumer to use the `rgb()` function in their stylesheets, but it also lets them control each token's alpha channel.
-
-```css
-.example {
-  color: rgb(var(--sl-color-sky-500));
-  background-color: rgb(var(--sl-color-sky-500) / 5%); /* 5% opacity */
-}
-```
-
 ### Form Controls
 
-Form controls should support validation through the following conventions:
+Form controls should support submission and validation through the following conventions:
 
-- All form controls must have an `invalid` property that reflects their validity
+- All form controls must use `name`, `value`, and `disabled` properties in the same manner as `HTMLInputElement`
 - All form controls must have a `setCustomValidity()` method so the user can set a custom validation message
 - All form controls must have a `reportValidity()` method that report their validity during form submission
+- All form controls must have an `invalid` property that reflects their validity
 - All form controls should mirror their native validation attributes such as `required`, `pattern`, `minlength`, `maxlength`, etc. when possible
-- All form controls must be serialized by `<sl-form>`
+- All form controls must be tested to work with the standard `<form>` element

docs/tokens/color.md

@@ -2,34 +2,8 @@
 
 Color tokens help maintain consistent use of color throughout your app. Shoelace provides palettes for theme colors and primitives that you can use as a foundation for your design system.
 
-## Usage
-
 Color tokens are referenced using the `--sl-color-{name}-{n}` CSS custom property, where `{name}` is the name of the palette and `{n}` is the numeric value of the desired swatch.
 
-All color tokens are defined as a set of RGB integers, eg. `113 113 122`. CSS doesn't understand this format, however, so you need wrap them in the `rgb()` function.
-
-```css
-.example {
-  color: rgb(var(--sl-color-neutral-500));
-}
-```
-
-This may seem a bit verbose, but it gives us a super power — we can adjust the alpha channel of any color token!
-
-## Adjusting Alpha Channels
-
-By default, color tokens produce an opaque color. With this syntax, you can easily adjust alpha channels.
-
-```css
-.example-with-alpha {
-  color: rgb(var(--sl-color-neutral-500) / 50%);
-}
-```
-
-The browser evaluates this to `rgb(113 113 122 / 50%)`, where 50% is the alpha value. Note the required `/` delimiter after the color token. Alternatively, you can use a decimal such as 0.5 in lieu of a percentage.
-
-This syntax may not look familiar, but it's perfectly valid per the [CSS Color Module Level 4](https://www.w3.org/TR/css-color-4/#typedef-color) and [well-supported](https://caniuse.com/mdn-css_types_color_space_separated_functional_notation) by modern browsers.
-
 ## Theme Tokens
 
 Theme tokens give you a semantic way to reference colors in your app. The primary palette is typically based on a brand color, whereas success, neutral, warning, and danger are used to visualize actions that correspond to their respective meanings.
@@ -39,17 +13,17 @@ Theme tokens give you a semantic way to reference colors in your app. The primar
     Primary<br>
     <code>--sl-color-primary-<em>{n}</em></code>
   </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-primary-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-primary-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-primary-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-primary-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-primary-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-primary-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-primary-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-primary-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-primary-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-primary-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-primary-950));"></div>950</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-primary-50);"></div>50</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-primary-100);"></div>100</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-primary-200);"></div>200</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-primary-300);"></div>300</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-primary-400);"></div>400</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-primary-500);"></div>500</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-primary-600);"></div>600</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-primary-700);"></div>700</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-primary-800);"></div>800</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-primary-900);"></div>900</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-primary-950);"></div>950</div>
 </div>
 
 <div class="color-palette">
@@ -57,17 +31,17 @@ Theme tokens give you a semantic way to reference colors in your app. The primar
     Success<br>
     <code>--sl-color-success-<em>{n}</em></code>
   </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-success-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-success-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-success-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-success-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-success-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-success-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-success-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-success-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-success-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-success-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-success-950));"></div>950</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-success-50);"></div>50</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-success-100);"></div>100</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-success-200);"></div>200</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-success-300);"></div>300</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-success-400);"></div>400</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-success-500);"></div>500</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-success-600);"></div>600</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-success-700);"></div>700</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-success-800);"></div>800</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-success-900);"></div>900</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-success-950);"></div>950</div>
 </div>
 
 <div class="color-palette">
@@ -75,17 +49,17 @@ Theme tokens give you a semantic way to reference colors in your app. The primar
     Warning<br>
     <code>--sl-color-warning-<em>{n}</em></code>
   </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-warning-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-warning-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-warning-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-warning-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-warning-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-warning-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-warning-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-warning-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-warning-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-warning-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-warning-950));"></div>950</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-warning-50);"></div>50</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-warning-100);"></div>100</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-warning-200);"></div>200</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-warning-300);"></div>300</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-warning-400);"></div>400</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-warning-500);"></div>500</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-warning-600);"></div>600</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-warning-700);"></div>700</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-warning-800);"></div>800</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-warning-900);"></div>900</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-warning-950);"></div>950</div>
 </div>
 
 <div class="color-palette">
@@ -93,17 +67,17 @@ Theme tokens give you a semantic way to reference colors in your app. The primar
     Danger<br>
     <code>--sl-color-danger-<em>{n}</em></code>
   </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-danger-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-danger-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-danger-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-danger-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-danger-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-danger-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-danger-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-danger-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-danger-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-danger-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-danger-950));"></div>950</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-danger-50);"></div>50</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-danger-100);"></div>100</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-danger-200);"></div>200</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-danger-300);"></div>300</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-danger-400);"></div>400</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-danger-500);"></div>500</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-danger-600);"></div>600</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-danger-700);"></div>700</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-danger-800);"></div>800</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-danger-900);"></div>900</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-danger-950);"></div>950</div>
 </div>
 
 <div class="color-palette">
@@ -111,17 +85,17 @@ Theme tokens give you a semantic way to reference colors in your app. The primar
     Neutral<br>
     <code>--sl-color-neutral-<em>{n}</em></code>
   </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-neutral-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-neutral-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-neutral-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-neutral-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-neutral-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-neutral-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-neutral-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-neutral-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-neutral-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-neutral-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-neutral-950));"></div>950</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-neutral-50);"></div>50</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-neutral-100);"></div>100</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-neutral-200);"></div>200</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-neutral-300);"></div>300</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-neutral-400);"></div>400</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-neutral-500);"></div>500</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-neutral-600);"></div>600</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-neutral-700);"></div>700</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-neutral-800);"></div>800</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-neutral-900);"></div>900</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-neutral-950);"></div>950</div>
 </div>
 
 <div class="color-palette">
@@ -129,8 +103,8 @@ Theme tokens give you a semantic way to reference colors in your app. The primar
     Black & White<br>
     <code>--sl-color-neutral-<em>{n}</em></code>
   </div>
-  <div class="color-palette__example"><div class="color-palette__swatch color-palette__swatch--border" style="background-color: rgb(var(--sl-color-neutral-0));"></div>0</div>
-  <div class="color-palette__example"><div class="color-palette__swatch " style="background-color: rgb(var(--sl-color-neutral-1000));"></div>1000</div>
+  <div class="color-palette__example"><div class="color-palette__swatch color-palette__swatch--border" style="background-color: var(--sl-color-neutral-0);"></div>0</div>
+  <div class="color-palette__example"><div class="color-palette__swatch " style="background-color: var(--sl-color-neutral-1000);"></div>1000</div>
 </div>
 
 ?> Looking for an easy way to customize your theme? [Try the color token generator!](https://codepen.io/claviska/full/QWveRgL)
@@ -140,94 +114,22 @@ Theme tokens give you a semantic way to reference colors in your app. The primar
 
 Additional palettes are provided in the form of color primitives. Use these when you need arbitrary colors that don't have semantic meaning. Color primitives are derived from the fantastic [Tailwind color palette](https://tailwindcss.com/docs/customizing-colors).
 
-<div class="color-palette">
-  <div class="color-palette__name">
-    Blue Gray<br>
-    <code>--sl-color-blue-gray-<em>{n}</em></code>
-  </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-blue-gray-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-blue-gray-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-blue-gray-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-blue-gray-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-blue-gray-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-blue-gray-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-blue-gray-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-blue-gray-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-blue-gray-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-blue-gray-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-blue-gray-950));"></div>950</div>
-</div>
-
-<div class="color-palette">
-  <div class="color-palette__name">
-    Cool Gray<br>
-    <code>--sl-color-cool-gray-<em>{n}</em></code>
-  </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-cool-gray-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-cool-gray-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-cool-gray-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-cool-gray-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-cool-gray-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-cool-gray-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-cool-gray-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-cool-gray-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-cool-gray-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-cool-gray-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-cool-gray-950));"></div>950</div>
-</div>
-
 <div class="color-palette">
   <div class="color-palette__name">
     Gray<br>
     <code>--sl-color-gray-<em>{n}</em></code>
   </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-gray-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-gray-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-gray-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-gray-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-gray-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-gray-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-gray-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-gray-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-gray-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-gray-900));"></div>900</div>  
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-gray-950));"></div>950</div>  
-</div>
-
-<div class="color-palette">
-  <div class="color-palette__name">
-    True Gray<br>
-    <code>--sl-color-true-gray-<em>{n}</em></code>
-  </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-true-gray-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-true-gray-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-true-gray-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-true-gray-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-true-gray-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-true-gray-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-true-gray-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-true-gray-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-true-gray-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-true-gray-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-true-gray-950));"></div>950</div>
-</div>
-
-<div class="color-palette">
-  <div class="color-palette__name">
-    Warm Gray<br>
-    <code>--sl-color-warm-gray-<em>{n}</em></code>
-  </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-warm-gray-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-warm-gray-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-warm-gray-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-warm-gray-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-warm-gray-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-warm-gray-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-warm-gray-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-warm-gray-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-warm-gray-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-warm-gray-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-warm-gray-950));"></div>950</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-gray-50);"></div>50</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-gray-100);"></div>100</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-gray-200);"></div>200</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-gray-300);"></div>300</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-gray-400);"></div>400</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-gray-500);"></div>500</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-gray-600);"></div>600</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-gray-700);"></div>700</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-gray-800);"></div>800</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-gray-900);"></div>900</div>  
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-gray-950);"></div>950</div>  
 </div>
 
 <div class="color-palette">
@@ -235,17 +137,17 @@ Additional palettes are provided in the form of color primitives. Use these when
     Red<br>
     <code>--sl-color-red-<em>{n}</em></code>
   </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-red-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-red-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-red-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-red-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-red-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-red-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-red-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-red-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-red-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-red-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-red-950));"></div>950</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-red-50);"></div>50</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-red-100);"></div>100</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-red-200);"></div>200</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-red-300);"></div>300</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-red-400);"></div>400</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-red-500);"></div>500</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-red-600);"></div>600</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-red-700);"></div>700</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-red-800);"></div>800</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-red-900);"></div>900</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-red-950);"></div>950</div>
 </div>
 
 <div class="color-palette">
@@ -253,17 +155,17 @@ Additional palettes are provided in the form of color primitives. Use these when
     Orange<br>
     <code>--sl-color-orange-<em>{n}</em></code>
   </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-orange-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-orange-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-orange-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-orange-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-orange-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-orange-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-orange-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-orange-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-orange-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-orange-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-orange-950));"></div>950</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-orange-50);"></div>50</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-orange-100);"></div>100</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-orange-200);"></div>200</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-orange-300);"></div>300</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-orange-400);"></div>400</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-orange-500);"></div>500</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-orange-600);"></div>600</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-orange-700);"></div>700</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-orange-800);"></div>800</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-orange-900);"></div>900</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-orange-950);"></div>950</div>
 </div>
 
 <div class="color-palette">
@@ -271,17 +173,17 @@ Additional palettes are provided in the form of color primitives. Use these when
     Amber<br>
     <code>--sl-color-amber-<em>{n}</em></code>
   </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-amber-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-amber-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-amber-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-amber-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-amber-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-amber-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-amber-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-amber-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-amber-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-amber-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-amber-950));"></div>950</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-amber-50);"></div>50</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-amber-100);"></div>100</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-amber-200);"></div>200</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-amber-300);"></div>300</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-amber-400);"></div>400</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-amber-500);"></div>500</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-amber-600);"></div>600</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-amber-700);"></div>700</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-amber-800);"></div>800</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-amber-900);"></div>900</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-amber-950);"></div>950</div>
 </div>
 
 <div class="color-palette">
@@ -289,17 +191,17 @@ Additional palettes are provided in the form of color primitives. Use these when
     Yellow<br>
     <code>--sl-color-yellow-<em>{n}</em></code>
   </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-yellow-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-yellow-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-yellow-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-yellow-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-yellow-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-yellow-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-yellow-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-yellow-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-yellow-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-yellow-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-yellow-950));"></div>950</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-yellow-50);"></div>50</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-yellow-100);"></div>100</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-yellow-200);"></div>200</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-yellow-300);"></div>300</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-yellow-400);"></div>400</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-yellow-500);"></div>500</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-yellow-600);"></div>600</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-yellow-700);"></div>700</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-yellow-800);"></div>800</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-yellow-900);"></div>900</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-yellow-950);"></div>950</div>
 </div>
 
 <div class="color-palette">
@@ -307,17 +209,17 @@ Additional palettes are provided in the form of color primitives. Use these when
     Lime<br>
     <code>--sl-color-lime-<em>{n}</em></code>
   </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-lime-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-lime-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-lime-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-lime-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-lime-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-lime-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-lime-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-lime-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-lime-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-lime-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-lime-950));"></div>950</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-lime-50);"></div>50</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-lime-100);"></div>100</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-lime-200);"></div>200</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-lime-300);"></div>300</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-lime-400);"></div>400</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-lime-500);"></div>500</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-lime-600);"></div>600</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-lime-700);"></div>700</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-lime-800);"></div>800</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-lime-900);"></div>900</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-lime-950);"></div>950</div>
 </div>
 
 <div class="color-palette">
@@ -325,17 +227,17 @@ Additional palettes are provided in the form of color primitives. Use these when
     Green<br>
     <code>--sl-color-green-<em>{n}</em></code>
   </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-green-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-green-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-green-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-green-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-green-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-green-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-green-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-green-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-green-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-green-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-green-950));"></div>950</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-green-50);"></div>50</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-green-100);"></div>100</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-green-200);"></div>200</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-green-300);"></div>300</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-green-400);"></div>400</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-green-500);"></div>500</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-green-600);"></div>600</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-green-700);"></div>700</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-green-800);"></div>800</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-green-900);"></div>900</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-green-950);"></div>950</div>
 </div>
 
 <div class="color-palette">
@@ -343,17 +245,17 @@ Additional palettes are provided in the form of color primitives. Use these when
     Emerald<br>
     <code>--sl-color-emerald-<em>{n}</em></code>
   </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-emerald-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-emerald-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-emerald-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-emerald-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-emerald-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-emerald-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-emerald-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-emerald-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-emerald-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-emerald-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-emerald-950));"></div>950</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-emerald-50);"></div>50</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-emerald-100);"></div>100</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-emerald-200);"></div>200</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-emerald-300);"></div>300</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-emerald-400);"></div>400</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-emerald-500);"></div>500</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-emerald-600);"></div>600</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-emerald-700);"></div>700</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-emerald-800);"></div>800</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-emerald-900);"></div>900</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-emerald-950);"></div>950</div>
 </div>
 
 <div class="color-palette">
@@ -361,17 +263,17 @@ Additional palettes are provided in the form of color primitives. Use these when
     Teal<br>
     <code>--sl-color-teal-<em>{n}</em></code>
   </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-teal-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-teal-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-teal-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-teal-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-teal-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-teal-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-teal-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-teal-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-teal-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-teal-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-teal-950));"></div>950</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-teal-50);"></div>50</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-teal-100);"></div>100</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-teal-200);"></div>200</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-teal-300);"></div>300</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-teal-400);"></div>400</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-teal-500);"></div>500</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-teal-600);"></div>600</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-teal-700);"></div>700</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-teal-800);"></div>800</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-teal-900);"></div>900</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-teal-950);"></div>950</div>
 </div>
 
 <div class="color-palette">
@@ -379,17 +281,17 @@ Additional palettes are provided in the form of color primitives. Use these when
     Cyan<br>
     <code>--sl-color-cyan-<em>{n}</em></code>
   </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-cyan-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-cyan-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-cyan-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-cyan-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-cyan-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-cyan-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-cyan-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-cyan-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-cyan-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-cyan-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-cyan-950));"></div>950</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-cyan-50);"></div>50</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-cyan-100);"></div>100</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-cyan-200);"></div>200</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-cyan-300);"></div>300</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-cyan-400);"></div>400</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-cyan-500);"></div>500</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-cyan-600);"></div>600</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-cyan-700);"></div>700</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-cyan-800);"></div>800</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-cyan-900);"></div>900</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-cyan-950);"></div>950</div>
 </div>
 
 <div class="color-palette">
@@ -397,17 +299,17 @@ Additional palettes are provided in the form of color primitives. Use these when
     Sky<br>
     <code>--sl-color-sky-<em>{n}</em></code>
   </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-sky-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-sky-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-sky-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-sky-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-sky-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-sky-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-sky-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-sky-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-sky-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-sky-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-sky-950));"></div>950</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-sky-50);"></div>50</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-sky-100);"></div>100</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-sky-200);"></div>200</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-sky-300);"></div>300</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-sky-400);"></div>400</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-sky-500);"></div>500</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-sky-600);"></div>600</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-sky-700);"></div>700</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-sky-800);"></div>800</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-sky-900);"></div>900</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-sky-950);"></div>950</div>
 </div>
 
 <div class="color-palette">
@@ -415,17 +317,17 @@ Additional palettes are provided in the form of color primitives. Use these when
     Blue<br>
     <code>--sl-color-blue-<em>{n}</em></code>
   </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-blue-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-blue-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-blue-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-blue-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-blue-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-blue-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-blue-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-blue-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-blue-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-blue-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-blue-950));"></div>950</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-blue-50);"></div>50</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-blue-100);"></div>100</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-blue-200);"></div>200</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-blue-300);"></div>300</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-blue-400);"></div>400</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-blue-500);"></div>500</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-blue-600);"></div>600</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-blue-700);"></div>700</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-blue-800);"></div>800</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-blue-900);"></div>900</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-blue-950);"></div>950</div>
 </div>
 
 <div class="color-palette">
@@ -433,17 +335,17 @@ Additional palettes are provided in the form of color primitives. Use these when
     Indigo<br>
     <code>--sl-color-indigo-<em>{n}</em></code>
   </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-indigo-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-indigo-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-indigo-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-indigo-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-indigo-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-indigo-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-indigo-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-indigo-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-indigo-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-indigo-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-indigo-950));"></div>950</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-indigo-50);"></div>50</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-indigo-100);"></div>100</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-indigo-200);"></div>200</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-indigo-300);"></div>300</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-indigo-400);"></div>400</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-indigo-500);"></div>500</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-indigo-600);"></div>600</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-indigo-700);"></div>700</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-indigo-800);"></div>800</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-indigo-900);"></div>900</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-indigo-950);"></div>950</div>
 </div>
 
 <div class="color-palette">
@@ -451,17 +353,17 @@ Additional palettes are provided in the form of color primitives. Use these when
     Violet<br>
     <code>--sl-color-violet-<em>{n}</em></code>
   </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-violet-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-violet-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-violet-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-violet-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-violet-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-violet-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-violet-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-violet-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-violet-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-violet-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-violet-950));"></div>950</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-violet-50);"></div>50</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-violet-100);"></div>100</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-violet-200);"></div>200</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-violet-300);"></div>300</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-violet-400);"></div>400</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-violet-500);"></div>500</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-violet-600);"></div>600</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-violet-700);"></div>700</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-violet-800);"></div>800</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-violet-900);"></div>900</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-violet-950);"></div>950</div>
 </div>
 
 <div class="color-palette">
@@ -469,17 +371,17 @@ Additional palettes are provided in the form of color primitives. Use these when
     Purple<br>
     <code>--sl-color-purple-<em>{n}</em></code>
   </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-purple-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-purple-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-purple-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-purple-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-purple-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-purple-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-purple-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-purple-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-purple-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-purple-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-purple-950));"></div>950</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-purple-50);"></div>50</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-purple-100);"></div>100</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-purple-200);"></div>200</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-purple-300);"></div>300</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-purple-400);"></div>400</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-purple-500);"></div>500</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-purple-600);"></div>600</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-purple-700);"></div>700</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-purple-800);"></div>800</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-purple-900);"></div>900</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-purple-950);"></div>950</div>
 </div>
 
 <div class="color-palette">
@@ -487,17 +389,17 @@ Additional palettes are provided in the form of color primitives. Use these when
     Fuchsia<br>
     <code>--sl-color-fuchsia-<em>{n}</em></code>
   </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-fuchsia-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-fuchsia-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-fuchsia-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-fuchsia-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-fuchsia-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-fuchsia-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-fuchsia-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-fuchsia-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-fuchsia-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-fuchsia-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-fuchsia-950));"></div>950</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-fuchsia-50);"></div>50</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-fuchsia-100);"></div>100</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-fuchsia-200);"></div>200</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-fuchsia-300);"></div>300</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-fuchsia-400);"></div>400</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-fuchsia-500);"></div>500</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-fuchsia-600);"></div>600</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-fuchsia-700);"></div>700</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-fuchsia-800);"></div>800</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-fuchsia-900);"></div>900</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-fuchsia-950);"></div>950</div>
 </div>
 
 <div class="color-palette">
@@ -505,17 +407,17 @@ Additional palettes are provided in the form of color primitives. Use these when
     Pink<br>
     <code>--sl-color-pink-<em>{n}</em></code>
   </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-pink-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-pink-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-pink-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-pink-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-pink-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-pink-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-pink-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-pink-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-pink-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-pink-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-pink-950));"></div>950</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-pink-50);"></div>50</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-pink-100);"></div>100</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-pink-200);"></div>200</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-pink-300);"></div>300</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-pink-400);"></div>400</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-pink-500);"></div>500</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-pink-600);"></div>600</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-pink-700);"></div>700</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-pink-800);"></div>800</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-pink-900);"></div>900</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-pink-950);"></div>950</div>
 </div>
 
 <div class="color-palette">
@@ -523,15 +425,15 @@ Additional palettes are provided in the form of color primitives. Use these when
     Rose<br>
     <code>--sl-color-rose-<em>{n}</em></code>
   </div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-rose-50));"></div>50</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-rose-100));"></div>100</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-rose-200));"></div>200</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-rose-300));"></div>300</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-rose-400));"></div>400</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-rose-500));"></div>500</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-rose-600));"></div>600</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-rose-700));"></div>700</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-rose-800));"></div>800</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-rose-900));"></div>900</div>
-  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: rgb(var(--sl-color-rose-950));"></div>950</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-rose-50);"></div>50</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-rose-100);"></div>100</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-rose-200);"></div>200</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-rose-300);"></div>300</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-rose-400);"></div>400</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-rose-500);"></div>500</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-rose-600);"></div>600</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-rose-700);"></div>700</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-rose-800);"></div>800</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-rose-900);"></div>900</div>
+  <div class="color-palette__example"><div class="color-palette__swatch" style="background-color: var(--sl-color-rose-950);"></div>950</div>
 </div>

docs/tutorials/integrating-with-laravel.md

@@ -1,19 +1,21 @@
 # Integrating with Laravel
 
-This page explains how to integrate Shoelace with a [Laravel](https://laravel.com) app using a local Webpack bundle. This is a community-maintained document. For questions about this integration, please [ask the community](/resources/community).
+This page explains how to integrate Shoelace with a [Laravel](https://laravel.com) app using a local Webpack bundle.
+
+?> This is a community-maintained document. Please [ask the community](/resources/community) if you have questions about this integration. You can also [suggest improvements](https://github.com/shoelace-style/shoelace/blob/next/docs/tutorials/integrating-with-laravel.md) to make it better.
 
 ## Requirements
 
 This integration has been tested with the following:
 
 - Laravel >= 8
-- Node >= 14
+- Node >= 14.17
 - Laravel Mix >= 6
 
 ## Instructions
 
-These instructions assume an out-of-the-box [Laravel 8+ install](https://laravel.com/docs/8.x/installation) that uses [Laravel Mix](https://laravel.com/docs/8.x/mix) to compile assets.
-Be sure to run `npm install` to install the default Laravel front-end dependencies before installing Shoelace. 
+These instructions assume an out of the box [Laravel 8+ install](https://laravel.com/docs/8.x/installation) that uses [Laravel Mix](https://laravel.com/docs/8.x/mix) to compile assets.
+Be sure to run `npm install` to install the default Laravel front-end dependencies before installing Shoelace.
 
 ### Install the Shoelace package
 
@@ -26,68 +28,70 @@ npm install @shoelace-style/shoelace
 Import Shoelace's default theme (stylesheet) in `/resources/css/app.css`:
 
 ```css
-@import "/node_modules/@shoelace-style/shoelace/dist/themes/light.css";
+@import '/node_modules/@shoelace-style/shoelace/dist/themes/light.css';
 ```
 
 ### Import Your Shoelace Components
 
-Import each Shoelace component you plan to use in `/resources/js/boostrap.js`. Since [Laravel Mix](https://laravel.com/docs/8.x/mix) uses Webpack, use the full path to each component -- as outlined in the [Cherry Picking instructions](https://shoelace.style/getting-started/installation?id=cherry-picking). You can find the full import statement for a component in the *Importing* section of the component's documentation (use the *Bundler* import). Your imports should look similar to:
+Import each Shoelace component you plan to use in `/resources/js/bootstrap.js`. Since [Laravel Mix](https://laravel.com/docs/8.x/mix) uses Webpack, use the full path to each component -- as outlined in the [Cherry Picking instructions](https://shoelace.style/getting-started/installation?id=cherry-picking). You can find the full import statement for a component in the _Importing_ section of the component's documentation (use the _Bundler_ import). Your imports should look similar to:
 
 ```js
-import "@shoelace-style/shoelace/dist/components/button/button.js";
-import "@shoelace-style/shoelace/dist/components/dialog/dialog.js";
-import "@shoelace-style/shoelace/dist/components/drawer/drawer.js";
-import "@shoelace-style/shoelace/dist/components/menu/menu.js";
-import "@shoelace-style/shoelace/dist/components/menu-item/menu-item.js";
+import '@shoelace-style/shoelace/dist/components/button/button.js';
+import '@shoelace-style/shoelace/dist/components/dialog/dialog.js';
+import '@shoelace-style/shoelace/dist/components/drawer/drawer.js';
+import '@shoelace-style/shoelace/dist/components/menu/menu.js';
+import '@shoelace-style/shoelace/dist/components/menu-item/menu-item.js';
 ```
 
 ### Set the Base Path
 
-Add the base path to your Shoelace assets (icons, images, etc.) in `/resources/js/boostrap.js`. The path must point to the same folder where you copy assets to in the next step.
+Add the base path to your Shoelace assets (icons, images, etc.) in `/resources/js/bootstrap.js`. The path must point to the same folder where you copy assets to in the next step.
 
 ```js
-import { setBasePath } from "@shoelace-style/shoelace/dist/utilities/base-path.js";
-setBasePath("/");
+import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path.js';
+setBasePath('/');
 ```
 
-Here's an example `/resources/js/boostrap.js` file, after importing and setting the base path and components.
+Here's an example `/resources/js/bootstrap.js` file, after importing and setting the base path and components.
 
 ```js
-import { setBasePath } from "@shoelace-style/shoelace/dist/utilities/base-path.js";
-setBasePath("/assets");
+import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path.js';
+setBasePath('/assets');
 
-import "@shoelace-style/shoelace/dist/components/button/button.js";
-import "@shoelace-style/shoelace/dist/components/dialog/dialog.js";
-import "@shoelace-style/shoelace/dist/components/drawer/drawer.js";
-import "@shoelace-style/shoelace/dist/components/menu/menu.js";
-import "@shoelace-style/shoelace/dist/components/menu-item/menu-item.js";
+import '@shoelace-style/shoelace/dist/components/button/button.js';
+import '@shoelace-style/shoelace/dist/components/dialog/dialog.js';
+import '@shoelace-style/shoelace/dist/components/drawer/drawer.js';
+import '@shoelace-style/shoelace/dist/components/menu/menu.js';
+import '@shoelace-style/shoelace/dist/components/menu-item/menu-item.js';
 ```
 
-
 ### Configure Laravel Mix
 
 [Laravel Mix](https://laravel.com/docs/8.x/mix) is a wrapper around Webpack that simplifies configuration. Mix is used by default for compiling front-end assets in Laravel.
 
 Modify `webpack.mix.js` to add Shoelace's assets to Webpack's build process:
+
 ```js
-mix.js("resources/js/app.js", "public/js")
-    .postCss("resources/css/app.css", "public/css", [])
-    .copy("node_modules/@shoelace-style/shoelace/dist/assets", "public/assets")
+mix
+  .js('resources/js/app.js', 'public/js')
+  .postCss('resources/css/app.css', 'public/css', [])
+  .copy('node_modules/@shoelace-style/shoelace/dist/assets', 'public/assets');
 ```
 
 Consider [extracting vendor libraries](https://laravel.com/docs/8.x/mix#vendor-extraction) to a separate file. This splits frequently updated vendor libraries (like Shoelace) from your front-end application code -- for better long-term caching.
 Here's an example `webpack.mix.js` file that compiles and splits your JS into `app.js` and `vendor.js` files, and builds an optimized CSS bundle using PostCSS.
 
 ```js
-mix.js("resources/js/app.js", "public/js")
-    .postCss("resources/css/app.css", "public/css", [])
-    .copy("node_modules/@shoelace-style/shoelace/dist/assets", "public/assets")
-    .extract(); // extracts libraries in node_modules to vendor.js
+mix
+  .js('resources/js/app.js', 'public/js')
+  .postCss('resources/css/app.css', 'public/css', [])
+  .copy('node_modules/@shoelace-style/shoelace/dist/assets', 'public/assets')
+  .extract(); // extracts libraries in node_modules to vendor.js
 ```
 
 ### Compile Front-End Assets
 
-Run the [Laravel Mix](https://laravel.com/docs/8.x/mix) npm scripts to build your application's CSS and JavaScript code. 
+Run the [Laravel Mix](https://laravel.com/docs/8.x/mix) npm scripts to build your application's CSS and JavaScript code.
 
 ```bash
 ## build a development bundle
@@ -99,16 +103,15 @@ npm run prod
 
 ### Include Front-End Assets in Your Layout File
 
-Most full-stack Laravel applications use [layouts](https://laravel.com/docs/8.x/blade#building-layouts) to define the basic structure of a page. 
-After compiling your front-end assets (above), include them in your top-level layouts/templates. The following example uses the [Laravel asset helper](https://laravel.com/docs/8.x/helpers#method-asset) to generate a full URL. 
+Most full-stack Laravel applications use [layouts](https://laravel.com/docs/8.x/blade#building-layouts) to define the basic structure of a page.
+After compiling your front-end assets (above), include them in your top-level layouts/templates. The following example uses the [Laravel asset helper](https://laravel.com/docs/8.x/helpers#method-asset) to generate a full URL.
 
 ```html
 <script defer src="{{ asset('js/manifest.js') }}"></script>
 <script defer src="{{ asset('js/vendor.js') }}"></script>
 <script defer src="{{ asset('/js/app.js') }}"></script>
 
-<link href="{{ asset('css/app.css') }}" rel="stylesheet">
+<link href="{{ asset('css/app.css') }}" rel="stylesheet" />
 ```
 
 Have fun using Shoelace components in your Laravel app!
-

docs/tutorials/integrating-with-nextjs.md

@@ -1,6 +1,8 @@
 # Integrating with NextJS
 
-This page explains how to integrate Shoelace with a NextJS app. This is a community-maintained document. For questions about this integration, please [ask the community](/resources/community).
+This page explains how to integrate Shoelace with a NextJS app.
+
+?> This is a community-maintained document. Please [ask the community](/resources/community) if you have questions about this integration. You can also [suggest improvements](https://github.com/shoelace-style/shoelace/blob/next/docs/tutorials/integrating-with-nextjs.md) to make it better.
 
 ## Requirements
 
@@ -14,7 +16,7 @@ This integration has been tested with the following:
 To get started using Shoelace with NextJS, the following packages must be installed.
 
 ```bash
-yarn add @shoelace-style/shoelace @shoelace-style/react-wrapper copy-webpack-plugin next-compose-plugins next-transpile-modules
+yarn add @shoelace-style/shoelace @shoelace-style/shoelace copy-webpack-plugin next-compose-plugins next-transpile-modules
 ```
 
 ### Importing the Default Theme
@@ -40,16 +42,16 @@ function CustomEls({ URL }) {
     if (customEls.current) {
       return;
     }
-    
-    const { setBasePath } = require("@shoelace-style/shoelace/dist/utilities/base-path");
+
+    const { setBasePath } = require('@shoelace-style/shoelace/dist/utilities/base-path');
 
     setBasePath(`${URL}/static/static`);
-    
+
     // This imports all components
-    require("@shoelace-style/shoelace/dist/shoelace");
+    require('@shoelace-style/shoelace/dist/shoelace');
 
     // If you want to selectively import components, replace this line with your own definitions
-    // require("@shoelace-style/shoelace/dist/components/button/button");
+    // require('@shoelace-style/shoelace/dist/components/button/button');
 
     customEls.current = true;
   }, [URL, customEls]);
@@ -75,7 +77,7 @@ function MyApp({ Component, pageProps, URL }) {
       {process.browser && <CustomEls URL={URL} />}
       <Component {...pageProps} />
     </>
-  )
+  );
 }
 ```
 
@@ -90,7 +92,7 @@ BASE_URL="localhost:3000"
 Then, modify your `MyApp` class in `_app.js` to pass this process environment into your render:
 
 ```javascript
-MyApp.getInitialProps = async (context) => {
+MyApp.getInitialProps = async context => {
   const URL = process.env.BASE_URL;
 
   return {
@@ -106,8 +108,8 @@ MyApp.getInitialProps = async (context) => {
 Next we need to add Shoelace's assets to the final build output. To do this, modify `next.config.js` to look like this.
 
 ```javascript
-const path = require("path");
-const CopyPlugin = require("copy-webpack-plugin");
+const path = require('path');
+const CopyPlugin = require('copy-webpack-plugin');
 const withPlugins = require('next-compose-plugins');
 const withTM = require('next-transpile-modules')(['@shoelace-style/shoelace']);
 
@@ -128,10 +130,8 @@ module.exports = withPlugins([withTM], {
 });
 ```
 
-?> This will copy the files from `node_modules` into your `static` folder on every development serve or build. You may want to avoid commiting these into your repo. To do so, simply add `static/assets` into your `.gitignore` folder
+?> This will copy the files from `node_modules` into your `static` folder on every development serve or build. You may want to avoid committing these into your repo. To do so, simply add `static/assets` into your `.gitignore` folder
 
 ## Additional Resources
 
 - There is a third-party [example repo](https://github.com/crutchcorn/nextjs-shoelace-example), courtesy of [crutchcorn](https://github.com/crutchcorn), available to help you get started.
-
-  

docs/tutorials/integrating-with-rails.md

@@ -1,6 +1,8 @@
 # Integrating with Rails
 
-This page explains how to integrate Shoelace with a Rails app. This is a community-maintained document. For questions about this integration, please [ask the community](/resources/community).
+This page explains how to integrate Shoelace with a Rails app.
+
+?> This is a community-maintained document. Please [ask the community](/resources/community) if you have questions about this integration. You can also [suggest improvements](https://github.com/shoelace-style/shoelace/blob/next/docs/tutorials/integrating-with-rails.md) to make it better.
 
 ## Requirements
 

lint-staged.config.js

@@ -0,0 +1,5 @@
+export default {
+  '*.{js,ts,json,html,xml,css,scss,sass,md}': 'cspell --no-must-find-files',
+  'src/**/*.{js,ts}': 'eslint --max-warnings 0 --fix',
+  '*': 'prettier --write --ignore-unknown'
+};