adobe
diff --git a/‎.cursor/rules/stories-documentation.mdc‎
Lines changed: 829 additions & 0 deletions b/‎.cursor/rules/stories-documentation.mdc‎
Lines changed: 829 additions & 0 deletions
diff --git a/‎.cursor/rules/stories-format.mdc‎
Lines changed: 666 additions & 0 deletions b/‎.cursor/rules/stories-format.mdc‎
Lines changed: 666 additions & 0 deletions
diff --git a/‎.cursor/rules/storybook-mdx-conversion.mdc‎
Lines changed: 117 additions & 0 deletions b/‎.cursor/rules/storybook-mdx-conversion.mdc‎
Lines changed: 117 additions & 0 deletions
diff --git a/‎.vscode/extensions.json‎
Lines changed: 4 additions & 1 deletion b/‎.vscode/extensions.json‎
Lines changed: 4 additions & 1 deletion
diff --git a/‎.vscode/local-extensions/README.md‎
Lines changed: 9 additions & 0 deletions b/‎.vscode/local-extensions/README.md‎
Lines changed: 9 additions & 0 deletions
diff --git a/‎.vscode/local-extensions/bierner.jsdoc-markdown-highlighting-0.0.1.vsix‎
26.1 KB b/‎.vscode/local-extensions/bierner.jsdoc-markdown-highlighting-0.0.1.vsix‎
26.1 KB
diff --git a/‎.vscode/settings.json‎
Lines changed: 11 additions & 2 deletions b/‎.vscode/settings.json‎
Lines changed: 11 additions & 2 deletions
diff --git a/‎1st-gen/packages/dialog/src/DialogBase.ts‎
Lines changed: 3 additions & 2 deletions b/‎1st-gen/packages/dialog/src/DialogBase.ts‎
Lines changed: 3 additions & 2 deletions
diff --git a/‎1st-gen/packages/dialog/src/DialogWrapper.ts‎
Lines changed: 1 addition & 0 deletions b/‎1st-gen/packages/dialog/src/DialogWrapper.ts‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎2nd-gen/README.md‎
Lines changed: 1 addition & 1 deletion b/‎2nd-gen/README.md‎
Lines changed: 1 addition & 1 deletion
@@ -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
@@ -1,3 +1,6 @@
 {
-    "recommendations": ["runem.lit-plugin"]
+    "recommendations": [
+        "runem.lit-plugin",
+        "bierner.jsdoc-markdown-highlighting"
+    ]
 }
@@ -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 install
@@ -1,7 +1,10 @@
 {
     "[mdx]": {
         "editor.wordWrapColumn": 120,
-        "editor.wordWrap": "bounded"
+        "editor.wordWrap": "bounded",
+        "editor.codeActionsOnSave": {
+            "source.organizeImports": "never"
+        }
     },
     "[markdown]": {
         "editor.wordWrapColumn": 120,
@@ -39,5 +42,11 @@
     },
     "typescript.tsdk": "node_modules/typescript/lib",
     "lit-plugin.strict": true,
-    "cSpell.words": ["activedescendant", "coachmark", "valuetext"]
+    "cSpell.words": [
+        "activedescendant",
+        "AUTODOCS",
+        "coachmark",
+        "effectful",
+        "valuetext"
+    ]
 }
@@ -20,16 +20,17 @@ import {
 } from '@spectrum-web-components/base';
 import { property } from '@spectrum-web-components/base/src/decorators.js';
 
-import '@spectrum-web-components/underlay/sp-underlay.js';
 import '@spectrum-web-components/button/sp-button.js';
+import '@spectrum-web-components/underlay/sp-underlay.js';
 
 // Leveraged in build systems that use aliasing to prevent multiple registrations: https://github.com/adobe/spectrum-web-components/pull/3225
+// eslint-disable-next-line import/no-extraneous-dependencies
 import '@spectrum-web-components/dialog/sp-dialog.js';
 import modalWrapperStyles from '@spectrum-web-components/modal/src/modal-wrapper.css.js';
 import modalStyles from '@spectrum-web-components/modal/src/modal.css.js';
-import { Dialog } from './Dialog.js';
 import { FocusVisiblePolyfillMixin } from '@spectrum-web-components/shared';
 import { firstFocusableIn } from '@spectrum-web-components/shared/src/first-focusable-in.js';
+import { Dialog } from './Dialog.js';
 
 /**
  * @element sp-dialog-base
 
@@ -23,6 +23,7 @@ import '@spectrum-web-components/button/sp-button.js';
 import '@spectrum-web-components/underlay/sp-underlay.js';
 
 // Leveraged in build systems that use aliasing to prevent multiple registrations: https://github.com/adobe/spectrum-web-components/pull/3225
+// eslint-disable-next-line import/no-extraneous-dependencies
 import '@spectrum-web-components/dialog/sp-dialog.js';
 import { Dialog } from './Dialog.js';
 import { DialogBase } from './DialogBase.js';
 
@@ -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
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,6 @@`
`1`	`1`	`{`
`2`		`- "recommendations": ["runem.lit-plugin"]`
	`2`	`+ "recommendations": [`
	`3`	`+ "runem.lit-plugin",`
	`4`	`+ "bierner.jsdoc-markdown-highlighting"`
	`5`	`+ ]`
`3`	`6`	`}`