@solid-design-system/mcp 0.0.1

package/metadata/packages/components/sd-select/info.md

@@ -0,0 +1,155 @@
+## Overview
+
+`<sd-select>` — Used to choose items from a menu of predefined options.
+
+## API
+
+### Examples
+
+Use the components tool by passing the args `component` and `example` for any of these combinations:
+
+- component: sd-select, example: size
+- component: sd-select, example: placement
+- component: sd-select, example: label
+- component: sd-select, example: floating-label
+- component: sd-select, example: placeholder
+- component: sd-select, example: disabled
+- component: sd-select, example: visually-disabled
+- component: sd-select, example: help-text
+- component: sd-select, example: clearable
+- component: sd-select, example: multiple
+- component: sd-select, example: use-tags
+- component: sd-select, example: max-options-visible
+- component: sd-select, example: required
+- component: sd-select, example: valid
+- component: sd-select, example: invalid
+
+### Key Properties
+
+- prop.defaultValue: string|string[], default='' — The default value of the form control. Primarily used for resetting the form control.
+- prop.open: boolean, default=false — Indicates whether or not the select is open. You can toggle this attribute to show and hide the menu, or you can
+  use the `show()` and `hide()` methods and this attribute will reflect the select's open state.
+- prop.size: 'lg'|'md'|'sm', default='lg' — The select's size.
+- prop.placement: 'top'|'bottom', default='bottom' — The preferred placement of the select's menu. Note that the actual placement may vary as needed to keep the listbox
+  inside of the viewport.
+- prop.label: string, default='' — The select's label. If you need to display HTML, use the `label` slot instead.
+- prop.placeholder: string, default='' — Placeholder text to show as a hint when the select is empty.
+- prop.maxOptionsTagLabel [attr: max-options-tag-label]: string, default='' — Label text shown on tag if max-options-visible is reached.
+- prop.disabled: boolean, default=false — Disables the select control.
+- prop.visuallyDisabled [attr: visually-disabled]: boolean, default=false — Styles the select as if it was disabled and enables aria-disabled
+- prop.helpText [attr: help-text]: string, default='' — The select's help text. If you need to display HTML, use the `help-text` slot instead.
+- prop.clearable: boolean, default=false — Adds a clear button when the select is not empty.
+- prop.multiple: boolean, default=false — Allows more than one option to be selected.
+- prop.useTags: boolean, default=false — Uses interactive `sd-tag` elements representing individual options in the display input when `multiple` is `true`.
+- prop.maxOptionsVisible [attr: max-options-visible]: number, default=3 — The maximum number of selected options to show when `multiple` and `useTags` are `true`. After the maximum, "+n" will be shown to
+  indicate the number of additional items that are selected. Set to 0 to remove the limit.
+- prop.form: string, default='' — By default, form controls are associated with the nearest containing `<form>` element. This attribute allows you
+  to place the form control outside of a form and associate it with the form that has this `id`. The form must be in
+  the same document or shadow root for this to work.
+- prop.name: string, default='' — The name of the select, submitted as a name/value pair with form data.
+- prop.value: string|string[], default='' — The current value of the select, submitted as a name/value pair with form data. When `multiple` is enabled, the
+  value attribute will be a space-delimited list of values based on the options selected, and the value property will
+  be an array. **For this reason, values must not contain spaces.**
+- prop.required: boolean, default=false — The select's required attribute.
+- prop.floatingLabel [attr: floating-label]: boolean, default=false — Enables the floating label behavior for the input.
+- prop.styleOnValid [attr: style-on-valid]: boolean, default=false — Shows success styles if the validity of the input is valid.
+- prop.hoist: boolean, default=false — Enable this option to prevent the listbox from being clipped when the component is placed inside a container with
+  `overflow: auto|scroll`. Hoisting uses a fixed positioning strategy that works in many, but not all, scenarios.
+- prop.validity: — Gets the validity state object
+- prop.validationMessage: — Gets the validation message
+- prop.dir: 'ltr'|'rtl'|'auto' — The element's directionality.
+- prop.lang: string — The element's language.
+
+### Events
+
+- event.sd-change: Emitted when the control's value changes.
+- event.sd-clear: Emitted when the control's value is cleared.
+- event.sd-input: Emitted when the control receives input.
+- event.sd-focus: Emitted when the control gains focus.
+- event.sd-blur: Emitted when the control loses focus.
+- event.sd-show: Emitted when the select's menu opens.
+- event.sd-after-show: Emitted after the select's menu opens and all animations are complete.
+- event.sd-hide: Emitted when the select's menu closes.
+- event.sd-after-hide: Emitted after the select's menu closes and all animations are complete.
+- event.sd-invalid: Emitted when the form control has been checked for validity and its constraints aren't satisfied.
+
+### Slots
+
+- slot.default: The listbox options. Must be `<sd-option>` elements. You can use `<sd-divider>` to group items visually.
+- slot.label: The input's label. Alternatively, you can use the `label` attribute.
+- slot.help-text: Text that describes how to use the input. Alternatively, you can use the `help-text` attribute.
+- slot.clear-icon: An icon to use in lieu of the default clear icon.
+- slot.expand-icon: The icon to show when the control is expanded and collapsed. Rotates on open and close.
+- slot.tooltip: An optional tooltip that helps describe the input. Use this slot with the `sd-tooltip` component.
+
+### CSS Parts
+
+- part.form-control: The form control that wraps the label, input, and help text.
+- part.form-control-label: The label's wrapper.
+- part.form-control-input: The select's wrapper.
+- part.form-control-help-text: The help text's wrapper.
+- part.combobox: The container the wraps the combobox, clear icon, and expand button.
+- part.display-input: The element that displays the selected option's label, an `<input>` element.
+- part.listbox: The listbox container where options are slotted.
+- part.tags: The container that houses option tags when `multiselect` is used.
+- part.tag: The individual tags that represent each multiselect option.
+- part.tag\_\_base: The tag's base part.
+- part.tag\_\_content: The tag's content part.
+- part.tag\_\_removable-indicator: The tag's remove button.
+- part.clear-button: The clear button.
+- part.expand-icon: The container that wraps the expand icon.
+
+## Guidelines
+
+### Use Cases
+
+- Enable users to select one or more options from a list of predefined choices in forms.
+- Implement in filter panels to allow users to refine search results or data views.
+- Provide options in settings pages where users need to choose preferences from a list.
+
+#### Default Select
+
+Use the “default” variant when clarity, scannability, and accessibility are your primary concerns.
+
+- Long or descriptive labels, helper text, or units are needed.
+- Forms with many fields that users must scan quickly.
+- Complex fields with adornments, counters, or tooltips.
+
+#### Floating Label Select
+
+Use the “floating-label” variant to conserve vertical space and streamline simple forms, while still keeping the label visible.
+
+- Compact layouts and simple fields.
+- Short labels (1–3 words); minimal helper text.
+- You want a clean look without duplicate placeholder text.
+
+### Rules
+
+### Variant Consistency
+
+Do not mix the two variants (default / floating label) within the same product, flow or form. Read the use cases above to know when to use each type.
+
+### Content and Labels
+
+- Keep each option to a single line of text for readability.
+- Ensure all options have consistent line lengths for easier scanning.
+- Avoid using the same word or phrase at the beginning of options.
+- Provide a meaningful placeholder option to guide users.
+
+### Selection Behavior
+
+- Use for lists with more than five options; for fewer options, consider using sd-radio for single selection or [sd-checkbox](./?path=/docs/components-sd-checkbox--docs) for multiple selection.
+- Apply the "multiple" attribute when multiple selections are allowed, and pair it with "checkbox" for corresponding nested options.
+- By default, the number of selected options is displayed after the text.
+- Display selected options as tags within the field to help users track their selections.
+- Consider limiting the maximum number of displayed selectable options to avoid overwhelming users. We recommend displaying 6-8 (with scrolling for additional results).
+
+### Background
+
+- Use light background options such as white, neutral-100, or primary-100.
+
+### Accessibility
+
+- If multiple options can be selected, clearly announce this capability to screenreader users and offer a way to view all chosen items.
+- Be aware that group labels in select components will be neglected by most assistive devices.
+- Use the "visually disabled" attribute to keep disabled elements focusable, hoverable, and able to show tooltips, as they’re otherwise removed from the tab order and inaccessible to screen readers.

package/metadata/packages/components/sd-select/stories/clearable.md

@@ -0,0 +1,13 @@
+Use the `clearable` attribute to add a clear button that removes the selected value.
+
+```html
+<div class="w-[400px] h-[500px]">
+  <sd-select size="lg" label="Label" placement="bottom" clearable="" value="option-1">
+    <sd-option value="option-1">Option 1</sd-option>
+    <sd-option value="option-2">Option 2</sd-option>
+    <sd-option value="option-3">Option 3</sd-option>
+    <sd-option value="option-4">Option 4</sd-option>
+    <sd-option value="option-5">Option 5</sd-option>
+  </sd-select>
+</div>
+```

package/metadata/packages/components/sd-select/stories/disabled.md

@@ -0,0 +1,13 @@
+Use the `disabled` attribute to disable the select.
+
+```html
+<div class="w-[400px]">
+  <sd-select size="lg" label="Label" placeholder="Disabled" placement="bottom" value="" disabled>
+    <sd-option value="option-1">Option 1</sd-option>
+    <sd-option value="option-2">Option 2</sd-option>
+    <sd-option value="option-3">Option 3</sd-option>
+    <sd-option value="option-4">Option 4</sd-option>
+    <sd-option value="option-5">Option 5</sd-option>
+  </sd-select>
+</div>
+```

package/metadata/packages/components/sd-select/stories/floating-label.md

@@ -0,0 +1,14 @@
+Use the `floating-label` attribute to enable a floating label on the select.
+**Note:** Floating labels only work with the `label` attribute. The `label` slot is not supported. Only the `lg` and `md` sizes are available.
+
+```html
+<div class="flex gap-12 w-[400px] h-[500px]">
+  <sd-select size="lg" label="Floating Label" floating-label placement="bottom" value="">
+    <sd-option value="option-1">Option 1</sd-option>
+    <sd-option value="option-2">Option 2</sd-option>
+    <sd-option value="option-3">Option 3</sd-option>
+    <sd-option value="option-4">Option 4</sd-option>
+    <sd-option value="option-5">Option 5</sd-option>
+  </sd-select>
+</div>
+```

package/metadata/packages/components/sd-select/stories/help-text.md

@@ -0,0 +1,23 @@
+Use the `help-text` attribute to provide additional context or instructions.
+For help texts that contain HTML, use the `help-text` slot instead.
+
+```html
+<div class="flex gap-12 h-[500px]">
+  <sd-select size="lg" label="Label" placement="bottom" value="" help-text="Help text attribute">
+    <sd-option value="option-1">Option 1</sd-option>
+    <sd-option value="option-2">Option 2</sd-option>
+    <sd-option value="option-3">Option 3</sd-option>
+    <sd-option value="option-4">Option 4</sd-option>
+    <sd-option value="option-5">Option 5</sd-option>
+  </sd-select>
+
+  <sd-select size="lg" label="Label" placement="bottom" value="">
+    <div slot="help-text" class="text-lg">Help text slot</div>
+    <sd-option value="option-1">Option 1</sd-option>
+    <sd-option value="option-2">Option 2</sd-option>
+    <sd-option value="option-3">Option 3</sd-option>
+    <sd-option value="option-4">Option 4</sd-option>
+    <sd-option value="option-5">Option 5</sd-option>
+  </sd-select>
+</div>
+```

package/metadata/packages/components/sd-select/stories/invalid.md

@@ -0,0 +1,30 @@
+The component gets `invalid` state when the form is not valid.
+
+```html
+<div class="w-[400px] h-[300px]">
+  <sd-select
+    size="lg"
+    placement="bottom"
+    label="Label"
+    placeholder="Please select"
+    style-on-valid=""
+    value=""
+    required=""
+    clearable=""
+    class="invalid-example"
+  >
+    <sd-option class="option" value="option-1">Option 1</sd-option>
+    <sd-option class="option" value="option-2">Option 2</sd-option>
+    <sd-option class="option" value="option-3">Option 3</sd-option>
+  </sd-select>
+</div>
+
+<script>
+  var invalidSelect = document.querySelector('.invalid-example');
+  setTimeout(() => {
+    invalidSelect.checkValidity();
+    invalidSelect.reportValidity();
+    invalidSelect.setCustomValidity('Please select at least one option.');
+  }, 500);
+</script>
+```

package/metadata/packages/components/sd-select/stories/label.md

@@ -0,0 +1,23 @@
+Use the `label` attribute to give the select element an accessible label.
+For labels that contain HTML, use the `label` slot instead.
+
+```html
+<div class="flex gap-12 h-[500px]">
+  <sd-select size="lg" label="Label attribute" placement="bottom" value="">
+    <sd-option value="option-1">Option 1</sd-option>
+    <sd-option value="option-2">Option 2</sd-option>
+    <sd-option value="option-3">Option 3</sd-option>
+    <sd-option value="option-4">Option 4</sd-option>
+    <sd-option value="option-5">Option 5</sd-option>
+  </sd-select>
+
+  <sd-select size="lg" placement="bottom" value="">
+    <div slot="label" class="text-lg">Label slot</div>
+    <sd-option value="option-1">Option 1</sd-option>
+    <sd-option value="option-2">Option 2</sd-option>
+    <sd-option value="option-3">Option 3</sd-option>
+    <sd-option value="option-4">Option 4</sd-option>
+    <sd-option value="option-5">Option 5</sd-option>
+  </sd-select>
+</div>
+```

package/metadata/packages/components/sd-select/stories/max-options-visible.md

@@ -0,0 +1,24 @@
+Use the `max-options-visible` attribute to define the maximum number of selected options that will be visible.
+**Hint:** It requires the `multiple` and `useTags` attributes to be set.<br />
+Once the maximum number of options is reached, the selection will display a message indicating how many additional options have been selected.<br />
+To remove the limit, set the attribute to `0`.
+
+```html
+<div class="w-[400px] h-[500px]">
+  <sd-select
+    size="lg"
+    label="Label"
+    placement="bottom"
+    multiple=""
+    value="option-1 option-2 option-3"
+    useTags
+    max-options-visible="2"
+  >
+    <sd-option value="option-1">Option 1</sd-option>
+    <sd-option value="option-2">Option 2</sd-option>
+    <sd-option value="option-3">Option 3</sd-option>
+    <sd-option value="option-4">Option 4</sd-option>
+    <sd-option value="option-5">Option 5</sd-option>
+  </sd-select>
+</div>
+```

package/metadata/packages/components/sd-select/stories/multiple.md

@@ -0,0 +1,14 @@
+Use the `multiple` attribute to allow multiple options to be selected.
+Use `--tag-max-width` to set the maximum width of the tags and to show an ellipsis, e.g. `<sd-select style="--tag-max-width: 40px">`. The default value is `15ch`
+
+```html
+<div class="w-[400px] h-[500px]">
+  <sd-select size="lg" label="Label" placement="bottom" multiple="" value="option-1 option-2">
+    <sd-option value="option-1">Option 1</sd-option>
+    <sd-option value="option-2">Option 2</sd-option>
+    <sd-option value="option-3">Option 3</sd-option>
+    <sd-option value="option-4">Option 4</sd-option>
+    <sd-option value="option-5">Option 5</sd-option>
+  </sd-select>
+</div>
+```

package/metadata/packages/components/sd-select/stories/placeholder.md

@@ -0,0 +1,13 @@
+Use the `placeholder` attribute to show a placeholder when no option is selected.
+
+```html
+<div class="w-[400px] h-[500px]">
+  <sd-select size="lg" label="Label" placeholder="Placeholder example" placement="bottom" value="">
+    <sd-option value="option-1">Option 1</sd-option>
+    <sd-option value="option-2">Option 2</sd-option>
+    <sd-option value="option-3">Option 3</sd-option>
+    <sd-option value="option-4">Option 4</sd-option>
+    <sd-option value="option-5">Option 5</sd-option>
+  </sd-select>
+</div>
+```

package/metadata/packages/components/sd-select/stories/placement.md

@@ -0,0 +1,24 @@
+Use the `placement` attribute to define where the select panel should appear:
+
+- `bottom` (default)
+- `top`
+
+```html
+<div class="flex items-center gap-12 h-[500px]">
+  <sd-select class="self-baseline" size="lg" label="Label" placement="bottom" value="">
+    <sd-option value="option-1">Option 1</sd-option>
+    <sd-option value="option-2">Option 2</sd-option>
+    <sd-option value="option-3">Option 3</sd-option>
+    <sd-option value="option-4">Option 4</sd-option>
+    <sd-option value="option-5">Option 5</sd-option>
+  </sd-select>
+
+  <sd-select size="lg" label="Label" placement="top" value="">
+    <sd-option value="option-1">Option 1</sd-option>
+    <sd-option value="option-2">Option 2</sd-option>
+    <sd-option value="option-3">Option 3</sd-option>
+    <sd-option value="option-4">Option 4</sd-option>
+    <sd-option value="option-5">Option 5</sd-option>
+  </sd-select>
+</div>
+```

package/metadata/packages/components/sd-select/stories/required.md

@@ -0,0 +1,13 @@
+Use the `required` attribute to mark the element as required. This can be used for form validation purposes.
+
+```html
+<div class="w-[400px] h-[400px]">
+  <sd-select size="lg" label="Required" placeholder="Please select" placement="bottom" value="" required="">
+    <sd-option value="option-1">Option 1</sd-option>
+    <sd-option value="option-2">Option 2</sd-option>
+    <sd-option value="option-3">Option 3</sd-option>
+    <sd-option value="option-4">Option 4</sd-option>
+    <sd-option value="option-5">Option 5</sd-option>
+  </sd-select>
+</div>
+```

package/metadata/packages/components/sd-select/stories/size.md

@@ -0,0 +1,34 @@
+Use the `size` attribute to change the size. It will cascade to slotted `sd-option` elements:
+
+- `lg` (default)
+- `md`
+- `sm`
+  **Note:** On the `floating-label` variant “sm” size is not available.
+
+```html
+<div class="flex gap-12 h-[500px]">
+  <sd-select size="lg" label="Label" placeholder="Large" placement="bottom" value="" class="test">
+    <sd-option value="option-1" size="lg">Option 1</sd-option>
+    <sd-option value="option-2" size="lg">Option 2</sd-option>
+    <sd-option value="option-3" size="lg">Option 3</sd-option>
+    <sd-option value="option-4" size="lg">Option 4</sd-option>
+    <sd-option value="option-5" size="lg">Option 5</sd-option>
+  </sd-select>
+
+  <sd-select size="md" label="Label" placeholder="Medium" placement="bottom" value="" class="test">
+    <sd-option value="option-1" size="md">Option 1</sd-option>
+    <sd-option value="option-2" size="md">Option 2</sd-option>
+    <sd-option value="option-3" size="md">Option 3</sd-option>
+    <sd-option value="option-4" size="md">Option 4</sd-option>
+    <sd-option value="option-5" size="md">Option 5</sd-option>
+  </sd-select>
+
+  <sd-select size="sm" label="Label" placeholder="Small" placement="bottom" value="">
+    <sd-option value="option-1" size="sm">Option 1</sd-option>
+    <sd-option value="option-2" size="sm">Option 2</sd-option>
+    <sd-option value="option-3" size="sm">Option 3</sd-option>
+    <sd-option value="option-4" size="sm">Option 4</sd-option>
+    <sd-option value="option-5" size="sm">Option 5</sd-option>
+  </sd-select>
+</div>
+```

package/metadata/packages/components/sd-select/stories/use-tags.md

@@ -0,0 +1,14 @@
+Use the `useTags` attribute to display selected options as tags using the `sd-tag` component.
+**Hint:** It requires the `multiple` attribute to be set.
+
+```html
+<div class="w-[400px] h-[500px]">
+  <sd-select size="lg" label="Label" placement="bottom" multiple="" value="option-1 option-2" useTags>
+    <sd-option value="option-1">Option 1</sd-option>
+    <sd-option value="option-2">Option 2</sd-option>
+    <sd-option value="option-3">Option 3</sd-option>
+    <sd-option value="option-4">Option 4</sd-option>
+    <sd-option value="option-5">Option 5</sd-option>
+  </sd-select>
+</div>
+```

package/metadata/packages/components/sd-select/stories/valid.md

@@ -0,0 +1,29 @@
+The component gets `valid` state when the input is valid.
+Use the `style-on-valid` attribute to automatically indicate and show a valid state.
+
+```html
+<div class="w-[400px] h-[400px]">
+  <sd-select
+    size="lg"
+    placement="bottom"
+    label="Label"
+    placeholder="Please select"
+    style-on-valid=""
+    value="option-1"
+    class="valid-example"
+  >
+    <sd-option class="option" value="option-1">Option 1</sd-option>
+    <sd-option class="option" value="option-2">Option 2</sd-option>
+    <sd-option class="option" value="option-3">Option 12</sd-option>
+  </sd-select>
+</div>
+
+<script>
+  var validSelect = document.querySelector('.valid-example');
+  var options = validSelect.querySelectorAll('.option');
+  setTimeout(() => {
+    validSelect.checkValidity();
+    validSelect.reportValidity();
+  }, 500);
+</script>
+```

package/metadata/packages/components/sd-select/stories/visually-disabled.md

@@ -0,0 +1,17 @@
+Use the `visually-disabled` attribute to style the component as if it was disabled and enable `aria-disabled` to allow it to be reachable by screen readers.
+**Hint:** When using this attribute, make sure to provide ways to inform the user why the element is disabled and how to enable it. This can be done by using the `help-text` attribute or wrapping the element in a sd-tooltip.
+**Accessibility Hint:** Disabling elements is not recommended for accessibility reasons.
+
+```html
+<div class="w-[400px] h-[200px] mt-12">
+  <sd-tooltip content="Visually disabled" trigger="hover focus" size="sm">
+    <sd-select size="lg" label="Label" placeholder="Visually disabled" placement="bottom" value="" visually-disabled>
+      <sd-option value="option-1">Option 1</sd-option>
+      <sd-option value="option-2">Option 2</sd-option>
+      <sd-option value="option-3">Option 3</sd-option>
+      <sd-option value="option-4">Option 4</sd-option>
+      <sd-option value="option-5">Option 5</sd-option>
+    </sd-select>
+  </sd-tooltip>
+</div>
+```

package/metadata/packages/components/sd-skeleton/info.md

@@ -0,0 +1,57 @@
+## Overview
+
+`<sd-skeleton>` — Used as a placeholder preview of the content before the data gets loaded to reduce load-time frustration.
+
+## API
+
+### Examples
+
+Use the components tool by passing the args `component` and `example` for any of these combinations:
+
+- component: sd-skeleton, example: variants
+
+### Key Properties
+
+- prop.variant: 'rectangular'|'circular', default='rectangular' — The shape variant when used without slotted content.
+- prop.dir: 'ltr'|'rtl'|'auto' — The element's directionality.
+- prop.lang: string — The element's language.
+
+### Slots
+
+- slot.default: The skeleton's content. When provided, adapts to the content's dimensions. When empty, displays according to the variant property.
+
+### CSS Parts
+
+- part.base: The component's base wrapper.
+
+## Guidelines
+
+### Use Cases
+
+- Represent the loading state of specific UI elements like titles, images, and body content on detailed pages.
+
+- Show placeholders for repeating elements such as items in a product grid or a list of search results.
+
+### Rules
+
+**Content and Styling**
+
+- Ensure skeleton screens closely resemble the layout of the final content to provide a smooth transition once the content is loaded.
+- Use a consistent skeleton style across similar components for uniformity.
+- Make skeletons non-interactive placeholders, not functional components.
+
+**Behavior and Interaction**
+
+- Use skeletons only for content that takes longer than one second to load, avoiding quick flashes.
+- Avoid showing skeletons for elements that aren't actually loading, as this can confuse or mislead users.
+- Do not rely solely on skeletons for loading feedback; consider providing text like "Loading" for better accessibility.
+- Provide smooth, subtle transitions from the skeleton to the loaded content.
+
+**Performance**
+
+- Ensure skeletons are lightweight to avoid overloading the page with complex or animated elements that can affect performance.
+
+### Accessibility
+
+- Use aria-hidden="true" on skeleton placeholders so screenreaders skip them.
+- Provide a meaningful status update while skeletons are visible (e.g., “Loading…” or a live region announcing updates) to inform assistive technology users that content is still being retrieved.

package/metadata/packages/components/sd-skeleton/stories/variants.md

@@ -0,0 +1,13 @@
+Use the `variant` attribute to set the skeleton's variant:
+
+- rectangular: Variant's height can be adjusted according to needs
+- circular: Variant's width and height can be adjusted according to needs
+
+```html
+<div class="h-full">
+  <div class="flex flex-row gap-4 w-full">
+    <sd-skeleton class="w-[154px] h-4"></sd-skeleton>
+    <sd-skeleton variant="circular" class="h-4 w-4"></sd-skeleton>
+  </div>
+</div>
+```

package/metadata/packages/components/sd-spinner/info.md

@@ -0,0 +1,53 @@
+## Overview
+
+`<sd-spinner>` — Used as a visual indicator with a looping animation that shows loading is in process.
+
+## API
+
+### Examples
+
+Use the components tool by passing the args `component` and `example` for any of these combinations:
+
+- component: sd-spinner, example: variants
+- component: sd-spinner, example: size
+
+### Key Properties
+
+- prop.color: 'primary'|'white'|'currentColor', default='currentColor' — The color color of the spinner.
+- prop.dir: 'ltr'|'rtl'|'auto' — The element's directionality.
+- prop.lang: string — The element's language.
+
+## Guidelines
+
+### Use Cases
+
+- Indicate that content is being loaded, such as when fetching data from a server or loading a new page.
+- Show ongoing background processes, like file uploads or data processing tasks.
+- Used within buttons or interactive elements to indicate that an action is being processed.
+- Apply to sections of a page that are loading independently, such as widgets or panels.
+- Display when a form is being submitted to show that the submission is in progress.
+
+### Rules
+
+### Content
+
+- Include a label or message to provide context about what is being loaded, especially if the loading time is long.
+
+### Behavior and Placement
+
+- Use for processes that take a short amount of time (typically under 4 seconds).
+- Apply within specific sections rather than blocking the entire page, unless absolutely necessary.
+- Place in a consistent location relative to the content it is loading.
+
+### Styling
+
+- Maintain consistency in size and style; avoid using spinners of varying sizes on the same page.
+
+### Background
+
+- Use light background options like white, neutral-100, primary-100, or use a primary background when inverted.
+
+### Accessibility
+
+- Assign role="status" or use a live region (e.g., aria-live="polite") to inform screen reader users of ongoing loading.
+- A spinner shouldn’t itself be focusable or interactive, nor prevent from navigating to other parts of the page while loading continues.

package/metadata/packages/components/sd-spinner/stories/size.md

@@ -0,0 +1,15 @@
+Use the CSS property `font-size` to scale the spinner proportionally.
+
+```html
+<div class="flex flex-row gap-12">
+  <div style="font-size: inherit">
+    <sd-spinner color="primary"></sd-spinner>
+  </div>
+  <div style="font-size: 2rem">
+    <sd-spinner color="primary"></sd-spinner>
+  </div>
+  <div style="font-size: 4rem">
+    <sd-spinner color="primary"></sd-spinner>
+  </div>
+</div>
+```