feat: introduce dual-generation monorepo architecture (#5785)

* chore: move repository contents under 1st-gen/

* build: configure root workspace and tooling

- Add root package.json with workspace delegating scripts
- Configure Yarn 4 with monorepo workspaces
- Set up lint-staged, commitlint, and patch-package
- Update .gitignore for dual-workspace structure
- Configure root-level linting and formatting rules

* feat: scaffold 2nd-gen workspace with components and tooling

- Create 2nd-gen workspace with separate package.json
- Add @spectrum-web-components/core package with shared base classes
- Implement 2nd-gen components: asset, alert-banner, divider, progress-circle, status-light, report-abuse-button
- Add @adobe/swc aggregator package
- Configure Vite-based Storybook for Spectrum 2
- Set up Vitest and Playwright testing infrastructure
- Add TypeScript path mappings for cross-generation imports

* ci: update automation for dual-workspace structure

- Update CircleCI config for 1st-gen and 2nd-gen paths
- Modify GitHub workflows for monorepo structure
- Update changeset configuration for dual-workspace
- Add Cursor rules for contributor documentation

* docs: add barebones architecture documentation

- Add comprehensive contributor documentation
- Document 1st-gen vs 2nd-gen split and migration paths
- Include component migration step-by-step guides
- Add project planning and workstream documentation
- Document release processes and testing strategies

* chore(tooling): adapt publishing workflow for new monorepo structure (#5851)

* chore: update and streamline publishing workflow for new monorepo structure

Refactors the publishing and release management workflow to support the
dual-generation monorepo architecture:

- Update Changesets configuration to recognize both 1st-gen and 2nd-gen
  workspaces, enabling independent versioning strategies

- Refactor release scripts to delegate to generation-specific publishing
  workflows rather than operating on a flat package structure

- Update CI/CD publishing jobs to build, test, and publish both generations
  with appropriate dependency handling for the shared Core library

- Preserve existing 1st-gen package publishing behavior to avoid disruption
  to current consumers

This workflow enables continuous delivery of improvements to 1st-gen customers
while supporting independent 2nd-gen package releases.

Author: rubencarvalho

.changeset/README.md

@@ -8,9 +8,9 @@ find the full documentation for it [in our repository](https://github.com/change
 
 Changesets are a way to manage versions and changelogs for monorepos. Each changeset:
 
--   Describes changes made in one or more packages
--   Indicates the type of change (major, minor, patch)
--   Contains a brief markdown summary of the changes
+- Describes changes made in one or more packages
+- Indicates the type of change (major, minor, patch)
+- Contains a brief markdown summary of the changes
 
 ## How to Add a Changeset
 
@@ -29,18 +29,25 @@ Changesets are a way to manage versions and changelogs for monorepos. Each chang
 
 The command will create a new markdown file in the `.changeset` directory with your changes.
 
+## Important: @spectrum-web-components/core and component updates
+
+When making changes to `@spectrum-web-components/core`, you **must** also include the corresponding `@spectrum-web-components` component in the same changeset to ensure the changes appear in the component's changelog. This is because `@spectrum-web-components/core` changes are internal and don't automatically propagate to the component changelogs.
+
+**Best practice**: Create a single changeset that includes both packages when updating core functionality that affects a specific component.
+
 ## Example Changeset
 
 A typical changeset file looks like this:
 
 ```markdown
 ---
+'@spectrum-web-components/core': patch
 '@spectrum-web-components/button': minor
 '@spectrum-web-components/theme': patch
 ---
 
--   **Added**: Added new variant `tertiary` to `<sp-button>` component [#9999](https://github.com/adobe/spectrum-web-components/pull/9999)
--   **Fixed**: Fixed `<sp-theme>` theme compatibility issues [#10000](https://github.com/adobe/spectrum-web-components/pull/10000)
+- **Added**: Added new variant `tertiary` to `<sp-button>` component [#9999](https://github.com/adobe/spectrum-web-components/pull/9999)
+- **Fixed**: Fixed `<sp-theme>` theme compatibility issues [#10000](https://github.com/adobe/spectrum-web-components/pull/10000)
 ```
 
 For our guidelines on writing changesets, see [our writing changesets guide](https://opensource.adobe.com/spectrum-web-components/guides/writing-changesets/).
@@ -61,6 +68,6 @@ We have a quick list of common questions to get you started engaging with this p
 
 ## Additional Resources
 
--   [Changesets Documentation](https://github.com/changesets/changesets)
--   [Common Questions](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)
--   [Detailed Release Process](https://github.com/changesets/changesets/blob/main/docs/detailed-explanation.md)
+- [Changesets Documentation](https://github.com/changesets/changesets)
+- [Common Questions](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)
+- [Detailed Release Process](https://github.com/changesets/changesets/blob/main/docs/detailed-explanation.md)

.changeset/config.json

@@ -7,12 +7,22 @@
         }
     ],
     "commit": false,
-    "fixed": [["@spectrum-web-components/*"]],
-    "linked": [],
+    "fixed": [
+        [
+            "@spectrum-web-components/*",
+            "!@spectrum-web-components/core",
+            "!@spectrum-web-components/1st-gen",
+            "!@spectrum-web-components/2nd-gen"
+        ]
+    ],
+    "linked": [["@adobe/swc", "@spectrum-web-components/core"]],
     "access": "public",
     "baseBranch": "main",
     "updateInternalDependencies": "patch",
-    "ignore": [],
+    "ignore": [
+        "@spectrum-web-components/1st-gen",
+        "@spectrum-web-components/2nd-gen"
+    ],
     "snapshot": {
         "useCalculatedVersion": true,
         "prereleaseTemplate": "{tag}.{datetime}"

.circleci/config.yml

@@ -0,0 +1,52 @@
+---
+description: Useful for updating auto-generated navigation and validating links in the contributor docs
+alwaysApply: false
+---
+
+# Contributor docs navigation and link validation
+
+## When to apply this rule
+
+Recognize and apply this rule when the user requests any of the following:
+- Update contributor docs navigation
+- Update nav / TOC / breadcrumbs in contributor docs
+- Regenerate contributor docs
+- Validate/verify links in contributor docs
+- Fix broken links in contributor docs
+- Any mention of "CONTRIBUTOR-DOCS" or "contributor docs" with "update", "nav", "links", or "verify"
+
+## Instructions location
+
+**Primary path:** `CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs/01_ai-agent-instructions.md`
+
+## What to do
+
+1. **Verify the instructions file exists** at the path above
+   - If the file exists, read it and follow the instructions for "Role 1: Operator"
+   - If the file does NOT exist, see "Self-correction procedure" below
+
+2. **Follow the AI agent instructions** to:
+   - Run the nav update script (which automatically validates links)
+   - Handle any broken links that are reported
+   - Report results to the user
+
+## Self-correction procedure
+
+If the instructions file is not found at the expected path:
+
+1. Search for the file using: `glob_file_search` with pattern `**/ai-agent-instructions.md`
+2. Filter results to find the one in `CONTRIBUTOR-DOCS/` folder
+3. Read the found file to confirm it contains the nav update instructions
+4. **Update this rule file** with the new path by modifying the "Primary path" line above
+5. Inform the user that you've updated the rule with the new location
+6. Continue with the nav update process
+
+## Quick reference
+
+The nav update process typically involves:
+- Running a Node.js script in the authoring-contributor-docs folder
+- The script automatically updates breadcrumbs, TOC, and validates all links
+- If broken links are found, fix straightforward issues automatically
+- Only consult the user for ambiguous cases
+
+Execution time is typically 20-200ms for the entire CONTRIBUTOR-DOCS tree.

.cursor/rules/contributor-doc-update.mdc

@@ -7,18 +7,19 @@
     "extends": [
         "eslint:recommended",
         "plugin:@typescript-eslint/recommended",
-        "plugin:prettier/recommended",
-        "plugin:lit-a11y/recommended",
-        "plugin:require-extensions/recommended"
+        "plugin:prettier/recommended"
+    ],
+    "ignorePatterns": [
+        "CONTRIBUTOR-DOCS/**/*",
+        "1st-gen/packages/icons/src/icons-*.svg.ts"
     ],
     "overrides": [
         {
             "extends": ["plugin:jsonc/recommended-with-jsonc"],
             "files": ["*.json"],
             "parser": "jsonc-eslint-parser",
             "rules": {
-                "jsonc/sort-keys": ["warn"],
-                "notice/notice": "off"
+                "jsonc/sort-keys": ["warn"]
             }
         },
         {
@@ -74,97 +75,56 @@
                             "cpu",
                             "publishConfig"
                         ],
-                        "pathPattern": "^$" // Top-level properties
+                        "pathPattern": "^$"
                     },
                     {
-                        /*
-                         * This rule excludes export conditions from alphabetical sorting.
-                         * Since node.js processes export conditions in order and chooses the
-                         * first match, they need to be ordered logically, not alphabetically.
-                         */
                         "order": { "type": "asc" },
-                        "pathPattern": "^(?!exports\\[).*" // All properties except export conditions
+                        "pathPattern": "^(?!exports\\[).*"
                     }
                 ]
             }
         },
         {
-            "files": ["scripts/*"],
+            "extends": ["./1st-gen/.eslintrc.json"],
+            "files": ["1st-gen/**/*"],
             "rules": {
-                "no-console": ["off"]
+                "notice/notice": [
+                    "error",
+                    {
+                        "mustMatch": "Copyright [0-9]{0,4} Adobe. All rights reserved.",
+                        "templateFile": "config/HEADER.js"
+                    }
+                ]
             }
         },
         {
-            "files": ["react/**/*.ts"],
+            "extends": ["./2nd-gen/.eslintrc.json"],
+            "files": ["2nd-gen/**/*"],
             "rules": {
-                "@typescript-eslint/no-explicit-any": "off"
+                "notice/notice": [
+                    "error",
+                    {
+                        "mustMatch": "Copyright [0-9]{0,4} Adobe. All rights reserved.",
+                        "templateFile": "config/HEADER.js"
+                    }
+                ]
             }
         }
     ],
     "parser": "@typescript-eslint/parser",
     "parserOptions": {
-        "ecmaVersion": 2020,
+        "ecmaVersion": "latest",
         "sourceType": "module"
     },
-    "plugins": [
-        "@typescript-eslint",
-        "notice",
-        "@spectrum-web-components",
-        "import",
-        "require-extensions"
-    ],
+    "plugins": ["@typescript-eslint", "notice"],
     "root": true,
     "rules": {
-        "@spectrum-web-components/prevent-argument-names": [
-            "error",
-            ["e", "ev", "evt", "err"]
-        ],
-        "curly": ["error", "all"],
-        "import/extensions": [
-            "error",
-            "ignorePackages",
-            {
-                "ts": "never"
-            }
-        ],
-        "import/prefer-default-export": "off",
-        "lit-a11y/click-events-have-key-events": [
-            "error",
-            {
-                "allowList": [
-                    "sp-button",
-                    "sp-action-button",
-                    "sp-checkbox",
-                    "sp-radio",
-                    "sp-switch",
-                    "sp-menu-item",
-                    "sp-clear-button",
-                    "sp-underlay"
-                ]
-            }
-        ],
         "no-console": [
             "error",
             {
                 "allow": ["warn", "error"]
             }
         ],
-        "no-debugger": 2,
-        "notice/notice": [
-            "error",
-            {
-                "mustMatch": "Copyright [0-9]{0,4} Adobe. All rights reserved.",
-                "templateFile": "config/license.js"
-            }
-        ],
-        "sort-imports": [
-            "error",
-            {
-                "allowSeparatedGroups": false,
-                "ignoreCase": true,
-                "ignoreDeclarationSort": true,
-                "ignoreMemberSort": false
-            }
-        ]
+        "no-debugger": 2
     }
 }

.eslintrc.json

@@ -1,8 +1,7 @@
 name: Browser Performance Tests
 
 on:
-    pull_request:
-        types: [opened, synchronize, reopened]
+    workflow_dispatch: # Only run manually, not on pull requests
 
 permissions:
     contents: read
@@ -45,22 +44,22 @@ jobs:
                   echo "Checking Chrome version..."
                   google-chrome --version
                   echo "Checking tachometer chromedriver version..."
-                  yarn tachometer --version
+                  cd 1st-gen && yarn tachometer --version
 
             - name: Tachometer the changed packages
-              run: yarn test:changed --browser=${{ matrix.browser }}
+              run: cd 1st-gen && yarn test:changed --browser=${{ matrix.browser }}
 
             - name: Create a dummy file to ensure at least one results file exists
-              run: touch tachometer.${{ matrix.browser }}-ran.txt
+              run: touch 1st-gen/tachometer.${{ matrix.browser }}-ran.txt
 
             - name: Archive ${{ matrix.browser }} tachometer results
               id: upload-artifact
               uses: actions/upload-artifact@v4
               with:
                   name: tachometer-results-${{ matrix.browser }}
                   path: |
-                      tach-results.${{ matrix.browser }}.*.json
-                      tachometer.${{ matrix.browser }}-ran.txt
+                      1st-gen/tach-results.${{ matrix.browser }}.*.json
+                      1st-gen/tachometer.${{ matrix.browser }}-ran.txt
 
     comment-performance:
         name: Comment tachometer performance results

.github/workflows/browser-tests.yml

@@ -1,32 +1,32 @@
 name: Coveralls Code Coverage
 
 on:
-    push:
-        branches:
-            - main
-    pull_request:
-        branches:
-            - main
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
 
 jobs:
-    code-coverage-report:
-        name: Generate and upload coverage report
-        runs-on: ubuntu-latest
-        steps:
-            - name: Checkout PR branch
-              uses: actions/checkout@v4
+  code-coverage-report:
+    name: Generate and upload coverage report
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout PR branch
+        uses: actions/checkout@v4
 
-            - name: Setup Job and Install Dependencies
-              uses: ./.github/actions/setup-job
+      - name: Setup Job and Install Dependencies
+        uses: ./.github/actions/setup-job
 
-            - name: Install Playwright
-              run: yarn playwright install --with-deps
+      - name: Install Playwright
+        run: cd 1st-gen && yarn playwright install --with-deps
 
-            - name: Run unit tests with coverage
-              run: yarn test:ci --config web-test-runner.config.ci-chromium.js --group unit --coverage
-              continue-on-error: true
+      - name: Run unit tests with coverage
+        run: cd 1st-gen && yarn test:ci --config web-test-runner.config.ci-chromium.js --group coveralls-ci --coverage
+        continue-on-error: true
 
-            - name: Upload coverage to Coveralls
-              uses: coverallsapp/github-action@v2
-              with:
-                  allow-empty: true
+      - name: Upload coverage to Coveralls
+        uses: coverallsapp/github-action@v2
+        with:
+          allow-empty: true

.github/workflows/coveralls.yml

@@ -103,7 +103,7 @@ jobs:
               run: yarn install --immutable
 
             - name: Lint styles
-              if: ${{ needs.changed_files.outputs.styles_added_files != '' || needs.changed_files.outputs.styles_modified_files != '' }}
+              # if: ${{ needs.changed_files.outputs.styles_added_files != '' || needs.changed_files.outputs.styles_modified_files != '' }}
               uses: reviewdog/[email protected]
               with:
                   fail_level: error
@@ -116,7 +116,7 @@ jobs:
 
             - name: ESLint
               uses: reviewdog/[email protected]
-              if: ${{ needs.changed_files.outputs.eslint_added_files != '' || needs.changed_files.outputs.eslint_modified_files != '' }}
+              # if: ${{ needs.changed_files.outputs.eslint_added_files != '' || needs.changed_files.outputs.eslint_modified_files != '' }}
               with:
                   fail_level: error
                   level: error