fixes #985

docs/components/checkbox.md

@@ -72,14 +72,17 @@ Use the `setCustomValidity()` method to set a custom validation message. This wi
   const form = document.querySelector('.custom-validity');
   const checkbox = form.querySelector('sl-checkbox');
   const errorMessage = `Don't forget to check me!`;
+
   // Set initial validity as soon as the element is defined
   customElements.whenDefined('sl-checkbox').then(() => {
     checkbox.setCustomValidity(errorMessage);
   });
+
   // Update validity on change
   checkbox.addEventListener('sl-change', () => {
     checkbox.setCustomValidity(checkbox.checked ? '' : errorMessage);
   });
+
   // Handle submit
   form.addEventListener('submit', event => {
     event.preventDefault();
@@ -91,19 +94,24 @@ Use the `setCustomValidity()` method to set a custom validation message. This wi
 ```jsx react
 import { useEffect, useRef } from 'react';
 import { SlButton, SlCheckbox } from '@shoelace-style/shoelace/dist/react';
+
 const App = () => {
   const checkbox = useRef(null);
   const errorMessage = `Don't forget to check me!`;
+
   function handleChange() {
     checkbox.current.setCustomValidity(checkbox.current.checked ? '' : errorMessage);
   }
+
   function handleSubmit(event) {
     event.preventDefault();
     alert('All fields are valid!');
   }
+
   useEffect(() => {
     checkbox.current.setCustomValidity(errorMessage);
   }, []);
+
   return (
     <form class="custom-validity" onSubmit={handleSubmit}>
       <SlCheckbox ref={checkbox} onSlChange={handleChange}>

docs/resources/changelog.md

@@ -19,6 +19,8 @@ _During the beta period, these restrictions may be relaxed in the event of a mis
 - Added `--indicator-transition-duration` custom property to `<sl-progress-ring>` [#986](https://github.com/shoelace-style/shoelace/issues/986)
 - Added the ability to cancel `sl-show` and `sl-hide` events in `<sl-details>` [#993](https://github.com/shoelace-style/shoelace/issues/993)
 - Added `focus()` and `blur()` methods to `<sl-radio-button>`
+- Added the `handle-icon` part to `<sl-image-comparer>`
+- Added `caret`, `check`, `grip-vertical`, `indeterminate`, and `radio` icons to the system library and removed `check-lg` [#985](https://github.com/shoelace-style/shoelace/issues/985)
 - Fixed a bug in `<sl-card>` that prevented the border radius to apply correctly to the header [#934](https://github.com/shoelace-style/shoelace/pull/934)
 - Fixed a bug in `<sl-button-group>` where the inner border disappeared on focus [#980](https://github.com/shoelace-style/shoelace/pull/980)
 - Fixed a bug that caused prefix/suffix animations in `<sl-input>` to wobble [#996](https://github.com/shoelace-style/shoelace/issues/996)

docs/resources/contributing.md

@@ -302,3 +302,13 @@ Form controls should support submission and validation through the following con
 - 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 tested to work with the standard `<form>` element
+
+### System Icons
+
+Avoid inlining SVG icons inside of templates. If a component requires an icon, make sure `<sl-icon>` is a dependency of the component and use the [system library](/components/icon#customizing-the-system-library):
+
+```html
+<sl-icon library="system" name="..."></sl-icon>
+```
+
+This will render the icons instantly whereas the default library will fetch them from a remote source. If an icon isn't available in the system library, you will need to add it to `library.system.ts`. Using the system library ensures that all icons load instantly and are customizable by users who wish to provide a custom resolver for the system library.