docs: Firefly images for when to use SWC page

.cursor/rules/storybook-mdx-conversion.mdc

@@ -0,0 +1,117 @@
+# Storybook MDX conversion
+
+Converts markdown files to MDX format compatible with Storybook rendering.
+
+## When to apply
+
+Apply this rule when converting `.md` files to `.mdx` files for display in Storybook, particularly for documentation pages in the 2nd-gen SWC Storybook guides.
+
+## Conversion steps
+
+### 1. File extension and imports
+
+- Change file extension from `.md` to `.mdx`
+- Add Storybook imports at the top of the file:
+
+```typescript
+import { Meta } from '@storybook/addon-docs/blocks';
+```
+
+- Add a blank line after imports
+
+### 2. Meta tag
+
+- Add a `<Meta title="Your Title Here" />` tag after the imports
+- The title should match the document's main heading
+- Add a blank line after the Meta tag
+
+### 3. Convert HTML comments to JSX comments
+
+Replace HTML comments with JSX-style comments:
+
+**Before (Markdown):**
+
+```markdown
+<!-- Document title (editable) -->
+```
+
+**After (MDX):**
+
+```mdx
+{/* Document title (editable) */}
+```
+
+### 4. Preserve all other content
+
+- Keep all markdown syntax as-is (headings, lists, links, code blocks, etc.)
+- Keep all `<details>` and `<summary>` HTML elements unchanged
+- Keep all list formatting and indentation unchanged
+- Preserve all relative link paths (e.g., `./01_contributor-guides/README.md`)
+- Do not modify any content within `<details>` blocks or navigation lists
+
+## Example transformation
+
+**Before (README.md):**
+
+```markdown
+<!-- Document title (editable) -->
+
+# Contributor Documentation
+
+<!-- Generated TOC - DO NOT EDIT -->
+
+<details open>
+<summary><strong>In this doc</strong></summary>
+
+- [About Spectrum Web Components](#about-spectrum-web-components)
+
+</details>
+
+<!-- Document content (editable) -->
+
+## About Spectrum Web Components
+
+Content here...
+```
+
+**After (README.mdx):**
+
+```mdx
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Contributor Documentation" />
+{/* Document title (editable) */}
+
+# Contributor Documentation
+
+{/* Generated TOC - DO NOT EDIT */}
+
+<details open>
+<summary><strong>In this doc</strong></summary>
+
+- [About Spectrum Web Components](#about-spectrum-web-components)
+
+</details>
+
+{/* Document content (editable) */}
+
+## About Spectrum Web Components
+
+Content here...
+```
+
+## Critical rules
+
+1. **Only add imports and Meta tag** - Do not modify any other structural elements
+2. **Preserve exact formatting** - Keep all whitespace, indentation, and line breaks
+3. **Convert ALL HTML comments** - Every `<!-- comment -->` must become `{/* comment */}`
+4. **Keep markdown links** - Do not convert `.md` links to `.mdx` (Storybook may need the original paths)
+5. **Blank lines matter** - Maintain blank line after imports and after Meta tag
+
+## Common mistakes to avoid
+
+❌ Don't change the document's heading structure
+❌ Don't modify navigation lists or TOC content
+❌ Don't convert markdown to JSX (keep lists as markdown lists)
+❌ Don't add extra formatting or styling
+❌ Don't forget to convert ALL HTML comments to JSX comments

.vscode/extensions.json

@@ -1,3 +1,6 @@
 {
-    "recommendations": ["runem.lit-plugin"]
+    "recommendations": [
+        "runem.lit-plugin",
+        "bierner.jsdoc-markdown-highlighting"
+    ]
 }

.vscode/local-extensions/README.md

@@ -0,0 +1,9 @@
+# Installing local extensions in Cursor
+
+The extensions in this directory are not available in Cursor but are in VSCode. The `vsix` file can be uploaded to Cursor locally to install the extension for usage.
+
+The following steps will get you started:
+
+1. Go to cursor, hit Cmd + Shift + P
+2. Search for “Extensions: Install from VSIX…”
+3. Select the extension file from this directory and download

.vscode/settings.json

@@ -31,5 +31,10 @@
     },
     "typescript.tsdk": "node_modules/typescript/lib",
     "lit-plugin.strict": true,
-    "cSpell.words": ["activedescendant", "coachmark", "valuetext"]
+    "cSpell.words": ["activedescendant", "AUTODOCS", "coachmark", "valuetext"],
+    "[mdx]": {
+        "editor.codeActionsOnSave": {
+            "source.organizeImports": "never"
+        }
+    }
 }

2nd-gen/README.md

@@ -7,7 +7,7 @@ This workspace contains the second generation of Spectrum Web Components, built
 - **[@spectrum-web-components/core](./packages/core)** - Abstract base classes providing shared functionality
 - **[@adobe/swc](./packages/swc)** - Concrete component implementations with styling
 
-## Getting Started
+## About SWC
 
 ```bash
 # Install dependencies from repository root

2nd-gen/packages/core/components/badge/Badge.types.ts

@@ -10,26 +10,33 @@
  * governing permissions and limitations under the License.
  */
 
+import type { ElementSize } from '@spectrum-web-components/core/shared/base/index.js';
+
 /*
  * @todo The S1 types can be removed once we are no longer maintaining 1st-gen.
  */
 
 export const FIXED_VALUES = [
-    'inline-start',
-    'inline-end',
     'block-start',
     'block-end',
+    'inline-start',
+    'inline-end',
 ] as const;
 
-export type FixedValues = (typeof FIXED_VALUES)[number];
+export const BADGE_VALID_SIZES = [
+    's',
+    'm',
+    'l',
+    'xl',
+] as const satisfies readonly ElementSize[];
 
 export const BADGE_VARIANTS_SEMANTIC = [
     'accent',
-    'neutral',
     'informative',
+    'neutral',
     'positive',
-    'negative',
     'notice',
+    'negative',
 ] as const;
 
 export const BADGE_VARIANTS_COLOR_S1 = [
@@ -68,6 +75,11 @@ export const BADGE_VARIANTS_S2 = [
     ...BADGE_VARIANTS_COLOR_S2,
 ] as const;
 
+export type FixedValues = (typeof FIXED_VALUES)[number];
+export type BadgeSize = (typeof BADGE_VALID_SIZES)[number];
+export type BadgeSemanticVariant = (typeof BADGE_VARIANTS_SEMANTIC)[number];
+export type BadgeColorVariantS1 = (typeof BADGE_VARIANTS_COLOR_S1)[number];
+export type BadgeColorVariantS2 = (typeof BADGE_VARIANTS_COLOR_S2)[number];
 export type BadgeVariantS1 = (typeof BADGE_VARIANTS_S1)[number];
 export type BadgeVariantS2 = (typeof BADGE_VARIANTS_S2)[number];
 export type BadgeVariant = BadgeVariantS1 | BadgeVariantS2;

2nd-gen/packages/core/components/divider/Divider.base.ts

@@ -29,6 +29,7 @@ import {
  */
 export abstract class DividerBase extends SizedMixin(SpectrumElement, {
     validSizes: DIVIDER_VALID_SIZES,
+    /**@todo the design spec says the default size is small but we declare no default size */
     noDefaultSize: true,
 }) {
     /**

2nd-gen/packages/core/components/divider/Divider.types.ts

@@ -12,7 +12,13 @@
 
 import type { ElementSize } from '@spectrum-web-components/core/shared/base/index.js';
 
-export const DIVIDER_VALID_SIZES: ElementSize[] = ['s', 'm', 'l'] as const;
+export const DIVIDER_VALID_SIZES = [
+    's',
+    'm',
+    'l',
+] as const satisfies ElementSize[];
 export const DIVIDER_STATIC_COLORS = ['white', 'black'] as const;
 
 export type DividerStaticColor = (typeof DIVIDER_STATIC_COLORS)[number];
+
+export type DividerSize = (typeof DIVIDER_VALID_SIZES)[number];

2nd-gen/packages/core/components/progress-circle/ProgressCircle.base.ts

@@ -36,8 +36,6 @@ import {
  * @slot - Accessible label for the progress circle.
  *
  *   Used to provide context about what is loading or progressing.
- *
- * @fires progress-change - Dispatched when the progress value changes
  */
 export abstract class ProgressCircleBase extends SizedMixin(SpectrumElement, {
     validSizes: PROGRESS_CIRCLE_VALID_SIZES,

2nd-gen/packages/core/components/progress-circle/ProgressCircle.types.ts

@@ -16,7 +16,7 @@ export const PROGRESS_CIRCLE_VALID_SIZES: ElementSize[] = [
     's',
     'm',
     'l',
-] as const;
+] as const satisfies ElementSize[];
 export const PROGRESS_CIRCLE_STATIC_COLORS_S1 = ['white'] as const;
 export const PROGRESS_CIRCLE_STATIC_COLORS_S2 = [
     ...PROGRESS_CIRCLE_STATIC_COLORS_S1,

2nd-gen/packages/core/components/status-light/StatusLight.types.ts

@@ -62,6 +62,22 @@ export const STATUSLIGHT_VARIANTS_S2 = [
     ...STATUSLIGHT_VARIANTS_COLOR_S2,
 ] as const;
 
+export type StatusLightSemanticVariantS1 =
+    (typeof STATUSLIGHT_VARIANTS_SEMANTIC_S1)[number];
+export type StatusLightSemanticVariantS2 =
+    (typeof STATUSLIGHT_VARIANTS_SEMANTIC_S2)[number];
+export type StatusLightSemanticVariant =
+    | StatusLightSemanticVariantS1
+    | StatusLightSemanticVariantS2;
+
+export type StatusLightColorVariantS1 =
+    (typeof STATUSLIGHT_VARIANTS_COLOR_S1)[number];
+export type StatusLightColorVariantS2 =
+    (typeof STATUSLIGHT_VARIANTS_COLOR_S2)[number];
+export type StatusLightColorVariant =
+    | StatusLightColorVariantS1
+    | StatusLightColorVariantS2;
+
 export type StatusLightVariantS1 = (typeof STATUSLIGHT_VARIANTS_S1)[number];
 export type StatusLightVariantS2 = (typeof STATUSLIGHT_VARIANTS_S2)[number];
 export type StatusLightVariant = StatusLightVariantS1 | StatusLightVariantS2;

2nd-gen/packages/core/shared/base/Base.ts

@@ -63,23 +63,25 @@ export function SpectrumMixin<T extends Constructor<ReactiveElement>>(
 ): T & Constructor<SpectrumInterface> {
     class SpectrumMixinElement extends constructor {
         /**
-         * @private
+         * @internal
          */
         public override shadowRoot!: ShadowRoot;
         private _dirParent?: HTMLElement;
 
         /**
-         * @private
+         * @internal
          */
         public override dir!: 'ltr' | 'rtl';
 
         /**
-         * @private
+         * @internal
          */
         public get isLTR(): boolean {
             return this.dir === 'ltr';
         }
-
+        /**
+         * @internal
+         */
         public hasVisibleFocusInTree(): boolean {
             const getAncestors = (root: Document = document): HTMLElement[] => {
                 // eslint-disable-next-line @spectrum-web-components/document-active-element

2nd-gen/packages/core/shared/base/version.ts

@@ -1,14 +1,2 @@
-/**
- * Copyright 2025 Adobe. All rights reserved.
- * This file is licensed to you under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License. You may obtain a copy
- * of the License at http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software distributed under
- * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
- * OF ANY KIND, either express or implied. See the License for the specific language
- * governing permissions and limitations under the License.
- */
-
 // Generated by genversion.
 export const version = '1.10.0';

2nd-gen/packages/core/shared/observe-slot-presence.ts

@@ -55,7 +55,7 @@ export function ObserveSlotPresence<T extends Constructor<ReactiveElement>>(
         }
 
         /**
-         *  @private
+         *  @internal
          */
         public get slotContentIsPresent(): boolean {
             if (lightDomSelectors.length === 1) {
@@ -71,6 +71,9 @@ export function ObserveSlotPresence<T extends Constructor<ReactiveElement>>(
         }
         private [slotContentIsPresent]: Map<string, boolean> = new Map();
 
+        /**
+         * @internal
+         */
         public getSlotContentPresence(selector: string): boolean {
             if (this[slotContentIsPresent].has(selector)) {
                 return this[slotContentIsPresent].get(selector) || false;
@@ -80,6 +83,9 @@ export function ObserveSlotPresence<T extends Constructor<ReactiveElement>>(
             );
         }
 
+        /**
+         * @internal
+         */
         public managePresenceObservedSlot = (): void => {
             let changes = false;
             lightDomSelectors.forEach((selector) => {

2nd-gen/packages/core/shared/observe-slot-text.ts

@@ -59,6 +59,9 @@ export function ObserveSlotText<T extends Constructor<ReactiveElement>>(
             });
         }
 
+        /**
+         * @internal
+         */
         @property({ type: Boolean, attribute: false })
         public slotHasContent = false;
 
@@ -68,6 +71,9 @@ export function ObserveSlotText<T extends Constructor<ReactiveElement>>(
         })
         private [assignedNodesList]!: NodeListOf<HTMLElement>;
 
+        /**
+         * @internal
+         */
         public manageTextObservedSlot(): void {
             if (!this[assignedNodesList]) {
                 return;

2nd-gen/packages/core/shared/utilities/capitalize.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/**
+ * Capitalizes the first character of a string.
+ *
+ * @param str - The string to capitalize
+ * @returns The capitalized string, or an empty string if the input is not a string
+ *
+ * @example
+ * ```typescript
+ * capitalize('hello') // Returns: 'Hello'
+ * capitalize('world') // Returns: 'World'
+ * capitalize('') // Returns: ''
+ * capitalize(undefined) // Returns: ''
+ * ```
+ */
+export function capitalize(str?: string): string {
+    if (typeof str !== 'string') {
+        return '';
+    }
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}