docs: align components and templates with design docs [skip chromatic] (

#1426)

packages/components/.storybook/preview-head.html

@@ -132,13 +132,14 @@
   /**
     * Optimize autodocs for templates
     */
-  .sbdocs-title + [id^='anchor--templates-'].sb-anchor,
-  h1.sbdocs-title + [id^='anchor--templates-'].sb-anchor + h2,
+  .sbdocs-title + * + [id^='anchor--templates-'].sb-anchor,
+  h1.sbdocs-title + * + [id^='anchor--templates-'].sb-anchor + h2,
   [id^='anchor--templates-'].sb-anchor > .sbdocs > .sb-bar,
   h2#stories + [id^='anchor--components-'].sb-anchor,
   h2#stories + [id^='anchor--styles-'].sb-anchor {
     display: none;
   }
+
   [id^='anchor--templates-'].sb-anchor > .sbdocs {
     padding: 0;
   }

packages/components/src/components/accordion-group/accordion-group.stories.ts

@@ -10,13 +10,12 @@ const { generateTemplate } = storybookTemplate('sd-accordion-group');
  *
  * Used to group multiple accordions together.
  *
- *  **Related templates**:
- * - [Accordion Group](?path=/docs/templates-accordion-group--docs)
- *
- *
- *  **Related components**:
+ * **Related components**:
  * - [sd-accordion](?path=/docs/components-sd-accordion--docs)
  *
+ * **Related templates**:
+ * - [Accordion Group](?path=/docs/templates-accordion-group--docs)
+ *
  */
 
 export default {
@@ -38,10 +37,6 @@ export default {
   }
 };
 
-/**
- * Vertical stack of sd-accordions.
- */
-
 export const Default = {
   render: (args: any) => {
     return generateTemplate({
@@ -52,35 +47,30 @@ export const Default = {
 };
 
 /**
- * Use `close-others` attribute to only have one accordion open at a time.
+ * Use the `close-others` attribute to only have one accordion open at a time.
  */
 
 export const CloseOthers = {
   name: 'Close Others',
   render: () => html`
     <sd-accordion-group close-others>
-      <sd-accordion summary="Shareholder Structure"
-        ><p>
-          Union Investment is the dedicated asset manager within the German cooperative financial network. All
-          shareholders are also part of the network, which ensures a stable and long-term ownership structure. This
-          allows us to maintain a sustainable business model and develop strong, long-term client relationships.
-        </p></sd-accordion
-      ><sd-accordion summary="Cooparative financial network"
-        ><p>Union Investment is the asset manager within the German cooperative financial Network.</p></sd-accordion
-      ><sd-accordion summary="Investment philosophy"
-        ><div class="sd-prose">
-          <p>
-            Our investment philosophy is based on our belief that markets are inefficient. Long-term outperformance is,
-            therefore, best achieved through a combination of fundamental research, actively managed security selection
-            and robust risk management. This conviction lies at the heart of all our investment solutions. We offer a
-            transparent investment process, which allows clients to keep track of our investment decisions.
-          </p>
-          <p>
-            We take an integrated approach to portfolio management, with every portfolio manager also acting as a senior
-            research specialist. This structure enhances the team’s commitment to the process and helps to ensure
-            accountability for investment performance.
-          </p>
-        </div>
+      <sd-accordion summary="Accordion 1">
+        <p>
+          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nibh justo ullamcorper odio tempor molestie phasellus
+          dui vel id. Velit in sed
+        </p>
+      </sd-accordion>
+      <sd-accordion summary="Accordion 2">
+        <p>
+          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nibh justo ullamcorper odio tempor molestie phasellus
+          dui vel id. Velit in sed
+        </p>
+      </sd-accordion>
+      <sd-accordion summary="Accordion 3">
+        <p>
+          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nibh justo ullamcorper odio tempor molestie phasellus
+          dui vel id. Velit in sed
+        </p>
       </sd-accordion>
     </sd-accordion-group>
   `

packages/components/src/components/accordion/accordion.stories.ts

@@ -11,13 +11,11 @@ const { generateTemplate } = storybookTemplate('sd-accordion');
  *
  * Used to show a brief summary and expands to display additional content.
  *
- *  **Related templates**:
- * - [Accordion Group](?path=/docs/templates-accordion-group--docs)
- *
- *
- *  **Related components**:
+ * **Related components**:
  * - [sd-accordion-group](?path=/docs/components-sd-accordion-group--docs)
  *
+ * **Related templates**:
+ * - [Accordion Group](?path=/docs/templates-accordion-group--docs)
  */
 
 export default {
@@ -26,7 +24,7 @@ export default {
   tags: ['!dev'],
   args: overrideArgs([
     { type: 'slot', name: 'default', value: '<div class="slot slot--border slot--text h-16">Default slot</div>' },
-    { type: 'attribute', name: 'summary', value: 'Default' }
+    { type: 'attribute', name: 'summary', value: 'Accordion' }
   ]),
   argTypes,
   parameters: {
@@ -38,10 +36,6 @@ export default {
   }
 };
 
-/**
- * Accordion shows a brief summary and expands to show additional content.
- */
-
 export const Default = {
   render: (args: any) => {
     return generateTemplate({
@@ -51,7 +45,7 @@ export const Default = {
 };
 
 /**
- * Use the attribute `open` to set the state of the accordion.
+ * Use the `open` attribute to set the state of the accordion.
  */
 
 export const Open = {

packages/components/src/components/badge/badge.stories.ts

@@ -12,7 +12,7 @@ const { generateTemplate } = storybookTemplate('sd-badge');
  * Used to visual indicate a quantity related to a particular element. Often displayed next to an icon or label.
  *
  * **Related templates**:
- * - [Button with Badge](?path=/docs/templates-button-with-badge--docs)
+ * - [Badge](?path=/docs/templates-badge--docs)
  *
  */
 
@@ -32,10 +32,6 @@ export default {
   decorators: [withActions] as any
 };
 
-/**
- * This shows the badge in its default state.
- */
-
 export const Default = {
   name: 'Default',
   render: (args: any) => {
@@ -44,12 +40,14 @@ export const Default = {
 };
 
 /**
- * Use the `variant` attribute to set the badge’s variant.
+ * Use the `variant` attribute to set the badge’s variant:
  *
- * - `default`: Utilized for standard emphasis.
- * - `success` and `error`: Alternative color options like green or red are employed to highlight specific notifications, without implying any semantic meaning.
+ * - `default`
+ * - `success`
+ * - `error`
+ *
+ * __Hint:__ Alternative color options like green or red are employed to highlight specific notifications, without implying any semantic meaning.
  */
-
 export const Variant = {
   name: 'Variant',
   render: () => html`
@@ -62,16 +60,21 @@ export const Variant = {
 };
 
 /**
- * Use the `size` attribute to set the badge’s size.
+ * Use the `size` attribute to set the badge’s size:
+ *
+ * - `lg` (default)
+ * - `md`
+ * - `sm`
+ *
  */
 
 export const Size = {
   name: 'Size',
   render: () => html`
     <div class="flex gap-12">
-      <sd-badge size="sm">8</sd-badge>
-      <sd-badge size="md">8</sd-badge>
       <sd-badge size="lg">8</sd-badge>
+      <sd-badge size="md">8</sd-badge>
+      <sd-badge size="sm">8</sd-badge>
     </div>
   `
 };

packages/components/src/components/brandshape/brandshape.stories.ts

@@ -51,9 +51,6 @@ export default {
   }
 };
 
-/**
- * Default: This shows sd-brandshape in its default state.
- */
 export const Default = {
   name: 'Default',
   render: (args: any) => {
@@ -62,7 +59,15 @@ export const Default = {
 };
 
 /**
- * Use the `variant` attribute to display the brandshape with different background colors.
+ * Use the `variant` attribute to set the color variant:
+ *
+ * - `primary` (default): Used on light backgrounds
+ * - `neutral-100`
+ * - `border-primary`: Used on light backgrounds
+ * <br>Change the fill color to match the background color
+ * - `image`
+ * - `white`: Used on primary, primary-100 and neutral-100 backgrounds
+ * - `border-white`: Used on primary background
  */
 
 export const Variant = {

packages/components/src/components/button/button.stories.ts

@@ -8,12 +8,12 @@ const { overrideArgs } = storybookHelpers('sd-button');
 const { generateTemplate } = storybookTemplate('sd-button'); // Replace with your custom element tag
 
 /**
- * **Used to allow users to perform actions with a single click.
+ * Used to allow users to perform actions with a single click.
  *
  * Buttons perform various functions (e.g. download, link) or activate other functions (e.g. filter). All buttons can be displayed with or without an icon. On small devices, the buttons are streched to full width.
  *
  * **Related templates**:
- * - [Button with Badge](?path=/docs/templates-button-with-badge--docs)
+ * - [Button with Badge](?path=/docs/templates-badge--docs#button-with-badge)
  */
 export default {
   tags: ['!dev'],
@@ -38,12 +38,12 @@ export const Default = {
 };
 
 /**
- * Use the `variant` attribute to set the button’s variant. Be sure to select the right one for the action you want to make available.
+ * 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).
+ * - `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)
  */
 
 export const Variants = {
@@ -53,14 +53,18 @@ export const Variants = {
         <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">CTA</sd-button>
+        <sd-button variant="cta">Call To Action</sd-button>
       </div>
     `;
   }
 };
 
 /**
- * Use the `size` attribute to change a button’s size. The default is `lg`. In tight spaces, consider using `md` or even `sm`.
+ * Use the `size` attribute to change a button’s size:
+ *
+ * - `lg` (default)
+ * - `md`
+ * - `sm`
  */
 export const Size = {
   render: () => {

packages/components/src/components/carousel-item/carousel-item.stories.ts

@@ -5,10 +5,13 @@ const { overrideArgs } = storybookHelpers('sd-carousel-item');
 const { generateTemplate } = storybookTemplate('sd-carousel-item');
 
 /**
- * Represents a slide within a carousel.
+ * Used to represent a slide within a carousel.
+ *
+ * **Related components**:
+ * - [sd-carousel](?path=/docs/components-sd-carousel--docs)
  *
  * **Related templates**:
- * - [Carousel with Images](?path=/docs/templates-carousel-with-images--docs)
+ * - [Carousel](?path=/docs/templates-carousel--docs)
  */
 
 export default {