chore(storybook): review and complete storybook docs (#6180)

* feat(badge): ensure visual s2 fidelity (#6114)

* docs(badge): update rendering-and-styling migration analysis
Clarify that fixed positioning is documented in design system guidance
and note new S2 badge variants (notification, indicator) tracked in SWC-1831.

* feat(badge): add no-label CSS class when label slot is empty
Add `swc-Badge--no-label` class via classMap when the default slot
has no text content, enabling CSS targeting of icon-only badges.

* fix(badge): updates padding block tokens and icon-only gap

* feat(badge): support for swc-icon internal

* feat(badge): icon only accessibility examples

* fix(badge): size types passing into swc-icon

* docs(badge): adds todo for missing variants

* fix(badge): dynamically passes size to slotted icon

* test(badge): anatomy test checks for children elements
previously, we were checking for text content when the badge icon slot
was just accepting strings. Now the anatomy story is using the swc-icon
internal component, so it never has text content (it's got HTML). the
badge test now checks for children.length instead.

* fix(badge): disabled text control for icon-slot

* fix(badge): a11y roles for icon only badges

* fix(badge): inline padding
- adds new --swc-badge-padding-inline-start custom prop to control the
inline padding start of a badge. it changes when there's an icon + label
vs. just the text label
- also fixes the gap property so that we just redefine the custom prop
for the badge gap instead

* docs(badge): add todo for icon only badge size story

* docs(rules): update docs on template vs custom html rendering

* docs: badge examples updated

* fix(badge): correct fallbacks for sized badge padding
Without this fallback, the start padding on a badge without an icon would
always resolve to the 75-scale token regardless of size, because
--swc-badge-padding-inline-start was never set in the size override blocks.

Adding --swc-badge-padding-inline as an intermediate fallback means
size overrides propagate to both sides automatically, while the :has()
rules can still override --swc-badge-padding-inline-start for the icon case.

* revert(badge): medium stays default size; neutral is default variant

* test(badge): update new default assertions

* docs(badge): adds @todo to default sizing discrepancy comment

* fix(badge): reduce selector specificity and refactor private padding tokens

* fix(badge): padding block properties corrected

* docs: correct updated css style guides with badge examples

* docs: fix typo

* docs(badge): use different badge variants per design docs

* docs(badge): adds tickets to todo comments

* style(progress-circle): clean up code styles (#6146)

* chore(storybook): review and complete storybook docs

* fix(storybook): revert icon test change to debug test failures

* fix(storybook): changes to align w/progress circle being set to indeterminate by default

* fix(storybook): correct test failure caused by string mismatch

* fix(storybook): correct test failures

* fix(testing): correct failing tests in 2nd gen

* fix(storybook): correct test failures

* chore(storybook): address feedback

* chore(storybook): address feedback

---------

Co-authored-by: Marissa Huysentruyt <69602589+marissahuysentruyt@users.noreply.github.com>
Co-authored-by: rise-erpelding <54716846+rise-erpelding@users.noreply.github.com>

Author: 3 people

2nd-gen/packages/swc/components/badge/stories/badge.stories.ts

@@ -77,6 +77,31 @@ argTypes['icon-slot'] = {
     'Accepts an icon element. The control is disabled. Use the Anatomy story to see icon usage. Enhancements to this control will be added in a future release.',
 };
 
+// @todo: create a select dropdown with all available/acceptable icons for a component.
+// For now, this arg is turned off in the control table since the string doesn't get parsed as HTML: SWC-1853
+argTypes['icon-slot'] = {
+  ...argTypes['icon-slot'],
+  control: false,
+  description:
+    'Accepts an icon element. The control is disabled. Use the Anatomy story to see icon usage. Enhancements to this control will be added in a future release.',
+};
+
+argTypes.outline = {
+  ...argTypes.outline,
+  table: {
+    ...argTypes.outline?.table,
+    defaultValue: { summary: 'false' },
+  },
+};
+
+argTypes.subtle = {
+  ...argTypes.subtle,
+  table: {
+    ...argTypes.subtle?.table,
+    defaultValue: { summary: 'false' },
+  },
+};
+
 /**
  * Similar to [status lights](/docs/components-status-light--readme), they use color and text to convey status or category information.
  *
@@ -429,6 +454,50 @@ export const TextWrapping: Story = {
   tags: ['behaviors'],
 };
 
+/**
+ * Badges flow naturally within prose text to annotate inline content such as headings,
+ * labels, list items, or table cells.
+ *
+ * Because `<swc-badge>` renders as `inline-flex`, it participates in the normal
+ * text flow without any extra wrapper styling required. Use small (`s`) badges in
+ * most inline contexts to avoid disrupting line height.
+ */
+export const Inline: Story = {
+  render: (args) => html`
+    <p>
+      Design system components
+      ${template({
+        ...args,
+        variant: 'accent',
+        'default-slot': 'Beta',
+        size: 's',
+      })}
+    </p>
+    <p>
+      API documentation
+      ${template({
+        ...args,
+        variant: 'positive',
+        'default-slot': 'Stable',
+        size: 's',
+      })}
+    </p>
+    <p>
+      Legacy components
+      ${template({
+        ...args,
+        variant: 'notice',
+        'default-slot': 'Deprecated',
+        size: 's',
+      })}
+    </p>
+  `,
+  parameters: {
+    flexLayout: 'column-stretch',
+  },
+  tags: ['behaviors'],
+};
+
 // ────────────────────────────────
 //    ACCESSIBILITY STORIES
 // ────────────────────────────────

2nd-gen/packages/swc/components/divider/stories/divider.stories.ts

@@ -42,6 +42,14 @@ argTypes['static-color'] = {
   options: [undefined, ...Divider.STATIC_COLORS],
 };
 
+argTypes.vertical = {
+  ...argTypes.vertical,
+  table: {
+    ...argTypes.vertical?.table,
+    defaultValue: { summary: 'false' },
+  },
+};
+
 /**
  * A divider is a visual separator that brings clarity to a layout by grouping and dividing
  * content in close proximity. Dividers help establish rhythm and hierarchy, making it easier
@@ -219,6 +227,48 @@ export const StaticColors: Story = {
 };
 StaticColors.storyName = 'Static colors';
 
+// ──────────────────────────────
+//    BEHAVIORS STORIES
+// ──────────────────────────────
+
+/**
+ * ### Layout orientation
+ *
+ * Dividers can be oriented **horizontally** (default) or **vertically** to match
+ * the layout they serve:
+ *
+ * - **Horizontal dividers** separate stacked content, such as sections beneath headings
+ * - **Vertical dividers** separate side-by-side items in a flex row (e.g., navigation breadcrumbs, toolbars)
+ *
+ * Vertical dividers require the parent to have an **explicit height** (`block-size`) —
+ * without it, `block-size: 100%` resolves to zero and the divider is invisible.
+ */
+export const LayoutOrientation: Story = {
+  render: (args) => html`
+    <nav
+      style="display: flex; align-items: center; gap: 8px; block-size: 24px;"
+    >
+      <span>Overview</span>
+      ${template({ ...args, size: 's', vertical: true })}
+      <span>Files</span>
+      ${template({ ...args, size: 's', vertical: true })}
+      <span>Settings</span>
+    </nav>
+    <div style="margin-block-start: 16px;">
+      <h4 style="margin: 0 0 8px 0;">Project details</h4>
+      ${template({ ...args, size: 'l' })}
+      <p style="margin: 8px 0 0 0;">
+        Review the project timeline and deliverables.
+      </p>
+    </div>
+  `,
+  parameters: {
+    flexLayout: 'column-stretch',
+  },
+  tags: ['behaviors'],
+};
+LayoutOrientation.storyName = 'Layout orientation';
+
 // ────────────────────────────────
 //    ACCESSIBILITY STORIES
 // ────────────────────────────────

2nd-gen/packages/swc/components/progress-circle/stories/progress-circle.stories.ts

@@ -91,7 +91,8 @@ const sizeLabels = {
 export const Playground: Story = {
   tags: ['autodocs', 'dev'],
   args: {
-    label: 'Uploading document',
+    size: 'm',
+    label: 'Processing request',
   },
 };
 
@@ -102,7 +103,7 @@ export const Playground: Story = {
 export const Overview: Story = {
   tags: ['overview'],
   args: {
-    label: 'Uploading document',
+    label: 'Processing request',
   },
 };
 
@@ -118,7 +119,6 @@ export const Overview: Story = {
  * 3. **Label** - Accessible text describing the operation (not visually rendered).
  *
  * > **A11y Note:** Light DOM children are not projected into the shadow tree, so content between the opening and closing tags does not supply an accessible name. Use the `label` attribute or property, or `aria-label` / `aria-labelledby` on the host.
- *
  */
 export const Anatomy: Story = {
   render: () => html`
@@ -165,9 +165,6 @@ export const Sizes: Story = {
     )}
   `,
   tags: ['options'],
-  args: {
-    progress: 25,
-  },
 };
 
 /**
@@ -186,7 +183,6 @@ export const StaticColors: Story = {
     )}
   `,
   args: {
-    progress: 60,
     label: 'Processing media',
   },
   tags: ['options'],
@@ -201,12 +197,34 @@ export const StaticColors: Story = {
 // ──────────────────────────
 
 /**
- * When no `progress` value is set, the component displays an animated indeterminate
- * loading indicator. This is the default state.
- * The `aria-valuenow` attribute is removed, signaling to assistive technologies
- * that the operation duration is unknown.
+ * Progress circles can show specific progress values from 0% to 100%.
+ * Set the `progress` attribute to a value between 0 and 100 to represent determinate progress.
+ * This automatically sets `aria-valuenow` to the provided value for screen readers.
+ */
+export const ProgressValues: Story = {
+  render: (args) => html`
+    ${template({ ...args, progress: 0, label: 'Starting download' })}
+    ${template({ ...args, progress: 25, label: 'Downloading (25%)' })}
+    ${template({ ...args, progress: 50, label: 'Downloading (50%)' })}
+    ${template({ ...args, progress: 75, label: 'Downloading (75%)' })}
+    ${template({ ...args, progress: 100, label: 'Download complete' })}
+  `,
+  tags: ['states'],
+  args: {
+    size: 'm',
+  },
+  parameters: {
+    'section-order': 2,
+  },
+};
+ProgressValues.storyName = 'Progress values';
+
+/**
+ * The default state — when `progress` is not set, the component displays an animated
+ * loading indicator. The `aria-valuenow` attribute is omitted, signaling to assistive
+ * technologies that the operation duration is unknown.
  *
- * Use indeterminate progress when:
+ * Use the default (no `progress`) when:
  * - The operation duration is unknown
  * - Progress cannot be accurately measured
  * - Multiple sub-operations are running in parallel
@@ -216,36 +234,80 @@ export const Indeterminate: Story = {
   args: {
     label: 'Processing request',
   },
-  parameters: {
-    'section-order': 1,
-  },
 };
 
+// ──────────────────────────────
+//    BEHAVIORS STORIES
+// ──────────────────────────────
+
 /**
- * Progress circles can show specific progress values from 0% to 100%.
- * Set the `progress` attribute to a value between 0 and 100 to represent determinate progress.
- * This automatically sets `aria-valuenow` to the provided value for screen readers.
+ * A common pattern is pairing a progress circle with a button to communicate
+ * that an action is in progress after the user clicks. Use `size="s"` to match
+ * typical button heights and `static-color="white"` on high-emphasis (filled)
+ * buttons where the icon sits on a colored background.
+ *
+ * Button loading states typically omit `progress` since the duration is unknown.
+ *
+ * @todo Refactor to use `<swc-button>` once the button component is available.
  */
-export const ProgressValues: Story = {
-  render: () => html`
-    <swc-progress-circle
-      progress="0"
-      label="Starting download"
-    ></swc-progress-circle>
-    <swc-progress-circle
-      progress="25"
-      label="Downloading (25%)"
-    ></swc-progress-circle>
-    <swc-progress-circle
-      progress="50"
-      label="Downloading (50%)"
-    ></swc-progress-circle>
+export const LoadingButton: Story = {
+  render: (args) => html`
+    <button
+      style="
+        display: inline-flex;
+        align-items: center;
+        gap: 8px;
+        padding: 6px 16px;
+        border: none;
+        border-radius: 16px;
+        background: var(--spectrum-accent-background-color-default, #378ef0);
+        color: #fff;
+        font: inherit;
+        font-size: 14px;
+        cursor: default;
+        opacity: 0.9;
+      "
+      disabled
+    >
+      ${template({
+        ...args,
+        size: 's',
+        'static-color': 'white',
+        label: 'Saving',
+      })}
+      Saving…
+    </button>
+    <button
+      style="
+        display: inline-flex;
+        align-items: center;
+        gap: 8px;
+        padding: 6px 16px;
+        border: 2px solid var(--spectrum-accent-background-color-default, #378ef0);
+        border-radius: 16px;
+        background: transparent;
+        color: var(--spectrum-accent-background-color-default, #378ef0);
+        font: inherit;
+        font-size: 14px;
+        cursor: default;
+        opacity: 0.9;
+      "
+      disabled
+    >
+      ${template({
+        ...args,
+        size: 's',
+        label: 'Processing',
+      })}
+      Processing…
+    </button>
   `,
-  tags: ['states'],
   parameters: {
-    'section-order': 2,
+    flexLayout: true,
   },
+  tags: ['behaviors'],
 };
+LoadingButton.storyName = 'Loading button';
 
 // ────────────────────────────────
 //    ACCESSIBILITY STORIES
@@ -262,7 +324,7 @@ export const ProgressValues: Story = {
  * 2. **Labeling**: Uses the `label` attribute value as `aria-label`, or rely on `aria-label` / `aria-labelledby` you set on the host
  * 3. **Progress state** (determinate):
  *     - Sets `aria-valuenow` with the current `progress` value
- * 4. **Loading state** (indeterminate):
+ * 4. **Loading state** (indeterminate — default when `progress` is unset):
  *     - When no `progress` value is set, `aria-valuenow` is omitted
  *     - Screen readers understand this as an ongoing operation with unknown duration
  * 5. **Status communication**: Screen readers announce progress updates as values change
@@ -296,8 +358,7 @@ export const ProgressValues: Story = {
 export const Accessibility: Story = {
   tags: ['a11y'],
   args: {
-    progress: 60,
     size: 'l',
-    label: 'Uploading presentation slides',
+    label: 'Syncing files',
   },
 };

2nd-gen/packages/swc/components/progress-circle/test/progress-circle.a11y.spec.ts

@@ -33,7 +33,7 @@ test.describe('Progress Circle - ARIA Snapshots', () => {
       'swc-progress-circle'
     );
     await expect(root).toMatchAriaSnapshot(`
-      - progressbar "Uploading document"
+      - progressbar "Processing request"
     `);
   });