@solid-design-system/mcp 0.0.1

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

@@ -0,0 +1,120 @@
+## Overview
+
+`<sd-button>` — Used to allow users to perform actions with a single click.
+
+## API
+
+### Examples
+
+Use the components tool by passing the args `component` and `example` for any of these combinations:
+
+- component: sd-button, example: variants
+- component: sd-button, example: size
+- component: sd-button, example: as-link
+- component: sd-button, example: loading
+- component: sd-button, example: disabled
+- component: sd-button, example: visually-disabled
+- component: sd-button, example: inverted
+- component: sd-button, example: icon
+
+### Key Properties
+
+- prop.title: string, default='' — The `title` attribute specifies extra information about an element most often as a default browser tooltip text when the mouse moves over the element.
+- prop.variant: 'primary'|'secondary'|'tertiary'|'cta', default='primary' — The button's theme variant.
+- prop.inverted: boolean, default=false — Inverts the button.
+- prop.size: 'lg'|'md'|'sm', default='lg' — The button's size.
+- prop.disabled: boolean, default=false — Disables the button.
+- prop.visuallyDisabled [attr: visually-disabled]: boolean, default=false — Styles the button as if it was disabled and enables aria-disabled
+- prop.loading: boolean, default=false — Draws the button in a loading state.
+- prop.type: 'button'|'submit'|'reset', default='button' — The type of button. Note that the default value is `button` instead of `submit`, which is opposite of how native
+  `<button>` elements behave. When the type is `submit`, the button will submit the surrounding form.
+- prop.name: string, default='' — The name of the button, submitted as a name/value pair with form data, but only when this button is the submitter.
+  This attribute is ignored when `href` is present.
+- prop.value: string, default='' — The value of the button, submitted as a pair with the button's name as part of the form data, but only when this
+  button is the submitter. This attribute is ignored when `href` is present.
+- prop.href: string, default='' — When set, the underlying button will be rendered as an `<a>` with this `href` instead of a `<button>`.
+- prop.target: '\_blank'|'\_parent'|'\_self'|'\_top' — Tells the browser where to open the link. Only used when `href` is present.
+- prop.download: string|undefined — Tells the browser to download the linked file as this filename. Only used when `href` is present.
+- prop.form: string — The "form owner" to associate the button with. If omitted, the closest containing form will be used instead. The
+  value of this attribute must be an id of a form in the same document or shadow root as the button.
+- prop.formAction [attr: formaction]: string — Used to override the form owner's `action` attribute.
+- prop.formEnctype [attr: formenctype]: 'application/x-www-form-urlencoded'|'multipart/form-data'|'text/plain' — Used to override the form owner's `enctype` attribute.
+- prop.formMethod [attr: formmethod]: 'post'|'get' — Used to override the form owner's `method` attribute.
+- prop.formNoValidate [attr: formnovalidate]: boolean — Used to override the form owner's `novalidate` attribute.
+- prop.formTarget [attr: formtarget]: '\_self'|'\_blank'|'\_parent'|'\_top' — Used to override the form owner's `target` attribute.
+- 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-blur: Emitted when the button loses focus.
+- event.sd-focus: Emitted when the button gains focus.
+- event.sd-invalid: Emitted when the form control has been checked for validity and its constraints aren't satisfied.
+
+### Slots
+
+- slot.default: The button's label.
+- slot.icon-left: A prefix icon or similar element.
+- slot.icon-right: A suffix icon or similar element.
+
+### CSS Parts
+
+- part.base: The component's base wrapper.
+- part.icon-left: The container that wraps the left icon area.
+- part.label: The button's label.
+- part.icon-right: The container that wraps the right icon area.
+- part.motion-wrapper: The container that wraps the motion animation.
+
+## Guidelines
+
+### Use Cases
+
+- Highlight key actions, like "Request information" or "Next step".
+- Provide supporting actions, like "Learn more", "Explore topic", or "Cancel".
+- Use for functional actions after user input, such as submitting a form or searching for content.
+
+### Rules
+
+### Function
+
+- Use to trigger an action or place a link inside it to navigate to other content.
+
+### Action Labels
+
+- Write simple, self-explanatory labels that include both a verb (action) and a noun.
+- Use text-only labels whenever possible.
+- Avoid generic labels like "OK" or “Download”. Use “Confirm selection” or “Download Report” instead.
+- Limit action labels to 1 to 3 words or 15 to 20 characters.
+
+### Action Priority
+
+- Select the appropriate variant for each action based on context and importance.
+- Avoid displaying more than one Call To Action (CTA) at a time on the screen, especially in the same context (e.g., teaser).
+
+### Icons
+
+- Add icons to labels only when they clearly support the associated action (e.g., print, email, share), and reserve icon-only buttons for exceptions.
+- Avoid displaying both left and right icons simultaneously.
+- To prevent overcrowding, do not use icons on buttons with extensive copy that spans multiple lines.
+
+### Placement and Responsiveness
+
+- Maintain consistent placement of interactive elements throughout the user interface.
+- Position the primary action at the top (in vertical layout) or on the right (in horizontal layout) when paired with a secondary option.
+- Avoid placing two primary actions next to each other; opt for a secondary action instead.
+- Expand to full width on small devices if applicable.
+
+### Background
+
+- Use light background options like white, neutral-100, primary-100, or use a primary background when inverted.
+
+### Accessibility
+
+- Ensure that button text is unique and contextual. Screen readers will read it aloud, helping users understand the action associated with the button.
+- Keep button text short. Longer copy is harder to scan and increases cognitive load. Remember that translations may double the length of the text.
+- Be aware that button’s height may change based on the user’s preferred font size set system-wide.
+- For icon-only: Include an ARIA label describing its function (e.g., “Expand section”) to ensure the button is accessible to screen readers.
+- Prefer keeping the button enabled by default by relying on default values or by validating on submit.
+- 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-button/stories/as-link.md

@@ -0,0 +1,12 @@
+- Use the `href` attribute to make it a link instead of a button.
+- Use the `target` attribute to specify where to open the link.
+- Use the `download` attribute to tell the browser to download the linked file as this filename.
+
+```html
+<div class="flex gap-12">
+  <sd-button href="https://solid-design-system.fe.union-investment.de/docs/?path=/docs/docs-general-introduction--docs"
+    >Link</sd-button
+  ><sd-button href="https://union-investment.com" target="_blank">New window</sd-button
+  ><sd-button href="./placeholders/src/images/collaboration.jpg" download>Download</sd-button>
+</div>
+```

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

@@ -0,0 +1,10 @@
+Use the `disabled` attribute to disable buttons.
+
+```html
+<div class="flex gap-12">
+  <sd-button variant="primary" disabled>Disabled</sd-button>
+  <sd-button variant="secondary" disabled>Disabled</sd-button>
+  <sd-button variant="tertiary" disabled>Disabled</sd-button>
+  <sd-button variant="cta" disabled>Disabled</sd-button>
+</div>
+```

package/metadata/packages/components/sd-button/stories/icon.md

@@ -0,0 +1,10 @@
+Use the `icon-left` or `icon-right` slot to add system icons.
+**Accessibility hint:** Only use icon-only buttons when the icon meaning is unambiguous. Consider also adding the `title` attribute to describe the icon’s underlying action.
+
+```html
+<div class="flex gap-12">
+  <sd-button>Icon left<sd-icon name="system/image" slot="icon-left"></sd-icon></sd-button>
+  <sd-button>Icon right<sd-icon name="system/image" slot="icon-right"></sd-icon></sd-button>
+  <sd-button title="icon only"><sd-icon name="system/image" label="Icon only"></sd-icon></sd-button>
+</div>
+```

package/metadata/packages/components/sd-button/stories/inverted.md

@@ -0,0 +1,10 @@
+Use the `inverted` attribute when displayed on primary background.
+
+```html
+<div class="flex gap-12 p-12 bg-primary">
+  <sd-button variant="primary" inverted>Inverted</sd-button>
+  <sd-button variant="secondary" inverted>Inverted</sd-button>
+  <sd-button variant="tertiary" inverted>Inverted</sd-button>
+  <sd-button variant="cta" inverted>Inverted</sd-button>
+</div>
+```

package/metadata/packages/components/sd-button/stories/loading.md

@@ -0,0 +1,10 @@
+Use the `loading` attribute to make a button busy. The width will remain the same as before, preventing adjacent elements from moving around.
+
+```html
+<div class="flex gap-12">
+  <sd-button variant="primary" loading>Loading</sd-button>
+  <sd-button variant="secondary" loading>Loading</sd-button>
+  <sd-button variant="tertiary" loading>Loading</sd-button>
+  <sd-button variant="cta" loading>Loading</sd-button>
+</div>
+```

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

@@ -0,0 +1,13 @@
+Use the `size` attribute to change a button’s size:
+
+- `lg` (default)
+- `md`
+- `sm`
+
+```html
+<div class="flex gap-12">
+  <sd-button size="lg">Large</sd-button>
+  <sd-button size="md">Medium</sd-button>
+  <sd-button size="sm">Small</sd-button>
+</div>
+```

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

@@ -0,0 +1,15 @@
+Use the `variant` attribute to set the button’s variant:
+
+- `primary` (default): Use the primary button for the most important actions in your interface, such as submitting a form, confirming a decision, or progressing to the next step in a process
+- `secondary`: Not all functions must have primary actions, sometimes the actions are subordinate to the content and all are equally important
+- `tertiary`: Use tertiary buttons for actions like accessing additional options, providing supplemental information, or performing less critical tasks
+- `cta` (Call to Action): The call-to-action button is only used once on a page (main conversion of the page)
+
+```html
+<div class="flex gap-12">
+  <sd-button variant="primary">Primary</sd-button>
+  <sd-button variant="secondary">Secondary</sd-button>
+  <sd-button variant="tertiary">Tertiary</sd-button>
+  <sd-button variant="cta">Call to action</sd-button>
+</div>
+```

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

@@ -0,0 +1,23 @@
+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="flex gap-12 h-[100px] mt-12">
+  <sd-tooltip content="Visually Disabled" trigger="hover focus" size="sm" placement="top">
+    <sd-button variant="primary" visually-disabled>Visually disabled</sd-button>
+  </sd-tooltip>
+
+  <sd-tooltip content="Visually Disabled" trigger="hover focus" size="sm" placement="top">
+    <sd-button variant="secondary" visually-disabled>Visually disabled</sd-button>
+  </sd-tooltip>
+
+  <sd-tooltip content="Visually Disabled" trigger="hover focus" size="sm" placement="top">
+    <sd-button variant="tertiary" visually-disabled>Visually disabled</sd-button>
+  </sd-tooltip>
+
+  <sd-tooltip content="Visually Disabled" trigger="hover focus" size="sm" placement="top">
+    <sd-button variant="cta" visually-disabled>Visually disabled</sd-button>
+  </sd-tooltip>
+</div>
+```

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

@@ -0,0 +1,99 @@
+## Overview
+
+`<sd-carousel>` — Used to display an arbitrary number of content slides along a horizontal axis.
+
+## API
+
+### Examples
+
+Use the components tool by passing the args `component` and `example` for any of these combinations:
+
+- component: sd-carousel, example: variant
+- component: sd-carousel, example: inverted
+- component: sd-carousel, example: loop
+- component: sd-carousel, example: autoplay
+- component: sd-carousel, example: autoplay-interval
+- component: sd-carousel, example: slides-per-page
+- component: sd-carousel, example: slides-per-move
+- component: sd-carousel, example: fade
+
+### Key Properties
+
+- prop.variant: 'dot'|'number', default='number' — Determines the counting system for the carousel.
+- prop.inverted: boolean, default=false — Inverts the carousel
+- prop.loop: boolean, default=false — When set, allows the user to navigate the carousel in the same direction indefinitely.
+- prop.autoplay: boolean, default=false — When set, the slides will scroll automatically when the user is not interacting with them.
+- prop.autoplayInterval [attr: autoplay-interval]: number, default=5 — Time (in seconds) between automatic slide transitions.
+- prop.fade: boolean, default=false — When set, slides will fade between each other instead of scrolling.
+- prop.slidesPerPage [attr: slides-per-page]: number, default=1 — Specifies how many slides should be shown at a given time.
+- prop.slidesPerMove [attr: slides-per-move]: number, default=1 — Use `slides-per-move` to set how many slides the carousel advances when scrolling. This is useful when specifying a `slides-per-page` greater than one. By setting `slides-per-move` to the same value as `slides-per-page`, the carousel will advance by one page at a time.<br>
+<b>Note:</b><br>
+<li> The number of slides should be divisible by the number of `slides-per-page` to maintain consistent scroll behavior.</li>
+<li>Variations between `slides-per-move` and `slides-per-page` can lead to unexpected scrolling behavior. Keep your intended UX in mind when adjusting these values.</li>
+- prop.dir: 'ltr'|'rtl'|'auto' — The element's directionality.
+- prop.lang: string — The element's language.
+
+### Events
+
+- event.sd-slide-change: Emitted when the active slide changes.
+
+### Slots
+
+- slot.default: The carousel's main content, one or more `<sd-carousel-item>` elements.
+- slot.next-icon: Optional next icon to use instead of the default. Works best with `<sd-icon>`.
+- slot.previous-icon: Optional previous icon to use instead of the default. Works best with `<sd-icon>`.
+- slot.autoplay-start: Optional start icon to use instead of the default. Works best with `<sd-icon>`.
+- slot.autoplay-pause: Optional pause icon to use instead of the default. Works best with `<sd-icon>`.
+
+### CSS Parts
+
+- part.base: The carousel's internal wrapper.
+- part.scroll-container: The scroll container that wraps the slides.
+- part.controls: A wrapper for the navigation and autoplay controller buttons.
+- part.pagination-dot: The pagination indicator in dot format.
+- part.pagination-number: The pagination indicator in number format.
+- part.pagination-item: The pagination indicator.
+- part.pagination-item--active: Applied when the item is active.
+- part.navigation: The navigation wrapper.
+- part.navigation-button: The navigation button.
+- part.navigation-button--previous: Applied to the previous button.
+- part.navigation-button--next: Applied to the next button.
+- part.autoplay-controls: A wrapper for pause/start button.
+
+## Guidelines
+
+### Use Cases
+
+- Highlight key features or promotions in a compact, rotating format.
+- Create interactive galleries for users to browse through images or videos.
+- Showcase testimonials or reviews to build credibility and trust.
+
+### Rules
+
+### Content and Style
+
+- Ensure consistency in content and style across slides by following a similar layout and type of information.
+
+### Usage and Interaction
+
+- Adapt the "slides per move" attribute to "slides per page" as needed, but keep the total number of available slides in mind: avoid moving more than one slide at a time if there are only a few slides.
+- Refrain from placing critical content in a rotating format, as users may miss it.
+- Enable swipe gestures to move slides on touch devices, while keeping the navigation arrows visible at all times.
+- Avoid enabling autoplay if possible. If necessary, ensure there is an option to stop any automatic movement.
+- Consider alternatives to carousels whenever possible, as they can be difficult for some users to navigate comfortably. Options such as accordions or tabs, for example, offer a more accessible way to present content.
+
+### Background
+
+- Use light background options like white, neutral-100, primary-100, or use a primary background when inverted.
+
+### Accessibility
+
+- Navigation arrows are still displayed on touch devices to enable alternative interaction that complies with accessibility requirements.
+- Always display the pause/play control when the carousel is set to autoplay.
+- Ensure sufficient contrast between each slide’s content and its background.
+
+#### ARIA Labels
+
+- Use appropriate ARIA roles, such as ’aria-roledescription="carousel"’and ”aria-live” to indicate the state of the carousel and announce dynamic changes to screen reader users.
+- Add the role="region" attribute together with an unique aria-label whenever the carousel is an important landmark of the page.
+- For purely decorative images, ALT-tags should be left empty so that screen readers can bypass them and concentrate on conveying meaningful content.

package/metadata/packages/components/sd-carousel/stories/autoplay-interval.md

@@ -0,0 +1,66 @@
+Use the `autoplay-interval` attribute to set the wait time (in seconds) between automatic slide transitions:
+
+- `5`(default): fast
+- `7`: medium
+- `10`: slow
+- `12`: very slow
+  The attribute `autoplay` needs to be set for this to work.
+  **Disclaimer**: Press the play button to start autoplay. It’s paused in Storybook to prevent screen reader confusion from multiple carousels on the page.
+
+```html
+<div class="flex flex-col gap-8">
+  <sd-carousel class="autoplay-pause" autoplay autoplay-interval="5" loop>
+    <sd-carousel-item
+      ><div class="slot slot--border slot--text h-16">Default slot 1 with 5s autoplay interval</div></sd-carousel-item
+    >
+    <sd-carousel-item
+      ><div class="slot slot--border slot--text h-16">Default slot 2 with 5s autoplay interval</div></sd-carousel-item
+    >
+    <sd-carousel-item
+      ><div class="slot slot--border slot--text h-16">Default slot 3 with 5s autoplay interval</div></sd-carousel-item
+    >
+  </sd-carousel>
+
+  <sd-carousel class="autoplay-pause" autoplay autoplay-interval="7" loop>
+    <sd-carousel-item
+      ><div class="slot slot--border slot--text h-16">Default slot 1 with 7s autoplay interval</div></sd-carousel-item
+    >
+    <sd-carousel-item
+      ><div class="slot slot--border slot--text h-16">Default slot 2 with 7s autoplay interval</div></sd-carousel-item
+    >
+    <sd-carousel-item
+      ><div class="slot slot--border slot--text h-16">Default slot 3 with 7s autoplay interval</div></sd-carousel-item
+    >
+  </sd-carousel>
+
+  <sd-carousel class="autoplay-pause" autoplay autoplay-interval="10" loop>
+    <sd-carousel-item
+      ><div class="slot slot--border slot--text h-16">Default slot 1 with 10s autoplay interval</div></sd-carousel-item
+    >
+    <sd-carousel-item
+      ><div class="slot slot--border slot--text h-16">Default slot 2 with 10s autoplay interval</div></sd-carousel-item
+    >
+    <sd-carousel-item
+      ><div class="slot slot--border slot--text h-16">Default slot 3 with 10s autoplay interval</div></sd-carousel-item
+    >
+  </sd-carousel>
+
+  <sd-carousel class="autoplay-pause" autoplay autoplay-interval="12" loop>
+    <sd-carousel-item
+      ><div class="slot slot--border slot--text h-16">Default slot 1 with 12s autoplay interval</div></sd-carousel-item
+    >
+    <sd-carousel-item
+      ><div class="slot slot--border slot--text h-16">Default slot 2 with 12s autoplay interval</div></sd-carousel-item
+    >
+    <sd-carousel-item
+      ><div class="slot slot--border slot--text h-16">Default slot 3 with 12s autoplay interval</div></sd-carousel-item
+    >
+  </sd-carousel>
+</div>
+
+<script type="module">
+  document.querySelectorAll('.autoplay-pause').forEach(carrousel => {
+    carrousel.pause();
+  });
+</script>
+```

package/metadata/packages/components/sd-carousel/stories/autoplay.md

@@ -0,0 +1,23 @@
+Use the `autoplay` attribute to toggle autoplay. Autoplay is automatically paused when the user interacts with
+the carousel or when the pause button is clicked.
+**Disclaimer**: Press the play button to start autoplay. It’s paused in Storybook to prevent screen reader confusion from multiple carousels on the page.
+
+```html
+<div>
+  <sd-carousel class="autoplay" autoplay loop>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 1</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 2</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 3</div>
+    </sd-carousel-item>
+  </sd-carousel>
+</div>
+<script type="module">
+  const carousel = document.querySelector('.autoplay');
+  carousel?.pause();
+</script>
+```

package/metadata/packages/components/sd-carousel/stories/fade.md

@@ -0,0 +1,18 @@
+Use the `fade` attribute to enable fading between slides.
+**Note**: The `fade` attribute is not compatible with the `slides-per-page` and `slides-per-move` attributes. If you use `fade`, the carousel will display one slide at a time.
+
+```html
+<div>
+  <sd-carousel loop fade>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 1</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 2</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 3</div>
+    </sd-carousel-item>
+  </sd-carousel>
+</div>
+```

package/metadata/packages/components/sd-carousel/stories/inverted.md

@@ -0,0 +1,17 @@
+Use the `inverted` attribute when displayed on primary background.
+
+```html
+<div class="bg-primary p-8">
+  <sd-carousel inverted>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text slot--inverted h-16">Default slot 1</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text slot--inverted h-16">Default slot 2</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text slot--inverted h-16">Default slot 3</div>
+    </sd-carousel-item>
+  </sd-carousel>
+</div>
+```

package/metadata/packages/components/sd-carousel/stories/loop.md

@@ -0,0 +1,17 @@
+Use the `loop` attribute to enable the looping of your slides.
+
+```html
+<div>
+  <sd-carousel loop>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 1</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 2</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 3</div>
+    </sd-carousel-item>
+  </sd-carousel>
+</div>
+```

package/metadata/packages/components/sd-carousel/stories/slides-per-move.md

@@ -0,0 +1,49 @@
+Use the `slides-per-move` attribute to configure the number of slides the carousel scrolls through at a time.
+This is useful when specifying a `slides-per-page` greater than one. By setting `slides-per-move` to the same value as `slides-per-page`, the carousel will advance by one page at a time.
+**Hints:**
+
+- The number of slides should be divisible by the number of `slides-per-page` to maintain consistent scroll behavior.
+- Variations between `slides-per-move` and `slides-per-page` can lead to unexpected scrolling behavior. Keep your intended UX in mind when adjusting these values.
+
+```html
+<div>
+  <sd-carousel slides-per-page="3" slides-per-move="3">
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 1</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 2</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 3</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 4</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 5</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 6</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 7</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 8</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 9</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 10</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 11</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 12</div>
+    </sd-carousel-item>
+  </sd-carousel>
+</div>
+```

package/metadata/packages/components/sd-carousel/stories/slides-per-page.md

@@ -0,0 +1,23 @@
+Use the `slides-per-page` attribute to set the number of slides displayed at once.
+
+```html
+<div>
+  <sd-carousel slides-per-page="2">
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 1</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 2</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 3</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 4</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 5</div>
+    </sd-carousel-item>
+  </sd-carousel>
+</div>
+```

package/metadata/packages/components/sd-carousel/stories/variant.md

@@ -0,0 +1,32 @@
+Use the `variant` attribute to select the pagination format:
+
+- `number` (default): can be used for all use cases
+- `dot`: can only be used for up to 5 items total
+
+```html
+<div class="flex gap-12">
+  <sd-carousel variant="number">
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 1</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 2</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 3</div>
+    </sd-carousel-item>
+  </sd-carousel>
+
+  <sd-carousel variant="dot">
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 1</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 2</div>
+    </sd-carousel-item>
+    <sd-carousel-item>
+      <div class="slot slot--border slot--text h-16">Default slot 3</div>
+    </sd-carousel-item>
+  </sd-carousel>
+</div>
+```

package/metadata/packages/components/sd-carousel-item/info.md

@@ -0,0 +1,26 @@
+## Overview
+
+`<sd-carousel-item>` — Used within `sd-carousel` to represent a slide.
+
+## API
+
+### Key Properties
+
+- prop.dir: 'ltr'|'rtl'|'auto' — The element's directionality.
+- prop.lang: string — The element's language.
+
+### Slots
+
+- slot.default: The carousel item's content.
+
+## Guidelines
+
+### Use Cases
+
+- Used within sd-carousel to represent a slide that could take a shape of an image or video, a quote among other options.
+
+### Rules
+
+### Content and Style
+
+- Ensure consistency in content and style across slides by following a similar layout and type of information.