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

Author: rubencarvalho

CONTRIBUTOR-DOCS/01_contributor-guides/01_getting-involved.md

@@ -0,0 +1,95 @@
+<!-- Generated breadcrumbs - DO NOT EDIT -->
+
+[CONTRIBUTOR-DOCS](../README.md) / [Contributor guides](README.md) / Getting involved
+
+<!-- Document title (editable) -->
+
+# Getting involved
+
+<!-- Generated TOC - DO NOT EDIT -->
+
+<details open>
+<summary><strong>In this doc</strong></summary>
+
+- [Welcome](#welcome)
+- [Community & support](#community--support)
+    - [External contributors](#external-contributors)
+    - [Internal contributors](#internal-contributors)
+- [How you can contribute](#how-you-can-contribute)
+- [Contributor license agreement](#contributor-license-agreement)
+- [Code of conduct](#code-of-conduct)
+- [Developing locally](#developing-locally)
+- [Thank you](#thank-you)
+
+</details>
+
+<!-- Document content (editable) -->
+
+## Welcome
+
+Welcome! We're excited you're interested in improving Spectrum Web Components. Whether you're reporting bugs, adding new features, writing documentation, or helping other users, your contributions make this project better for everyone.
+
+Here you'll find a broad overview of how you can get involved. Please read through these guidelines to help keep the contribution process smooth and to ensure we're all on the same page.
+
+## Community & support
+
+A fantastic first step to contributing is filing an issue. This is where you can:
+
+- Ask questions, file bugs, and troubleshoot with other users.
+- Propose new features and ideas or get feedback on your own through a linked pull request.
+- Additionally, you can check GitHub Discussions to stay up-to-date with any major announcements about the project.
+
+### External contributors
+
+**Adobe Employees, read Internal contributors section below.**
+If you need support or have a question about how something works, filing an issue is the best place to start. A team member will be in touch to either triage your issue or follow-up with you in the comments.
+
+### Internal contributors
+
+If you work for Adobe, our Slack channel #spectrum_web_components has some great workflows to get you started. Be sure to read the Welcome Canvas when you join.
+
+---
+
+## How you can contribute
+
+There's a common misconception that you need to code in order to contribute. In reality, there are many different ways to help:
+
+- Filing well-structured bug reports that show what's broken and how to reproduce it.
+- Suggesting new features that improve the current design system.
+- Improving our documentation to make it clearer for the next person.
+- Reviewing pull requests from other community members and sharing feedback.
+- Helping other users on GitHub Discussions.
+- Advocating for the project on social media or at meetups.
+
+Of course, contributing code is also welcome, from fixing a bug to building a brand-new component. All types of contributions help keep Spectrum Web Components thriving.
+
+---
+
+## Contributor license agreement
+
+We require all external contributors to sign our [Contributor License Agreement](https://opensource.adobe.com/cla.html) (CLA). If you haven't signed it before making your first contribution, please do so—otherwise, we can't merge your changes.
+
+---
+
+## Code of conduct
+
+Spectrum Web Components abides by the [Adobe Code of Conduct](../../CODE_OF_CONDUCT.md). By participating, you agree to treat all community members kindly and respectfully. We're committed to fostering a welcoming, inclusive environment.
+Should any behavior fall short of these expectations, please report it to <[email protected]>.
+
+---
+
+## Developing locally
+
+Read the steps outlined in the [README.md](../README.md) to get your environment set up.
+
+If you encounter hurdles, feel free to ask for help in your pull request or in the community forum.
+
+---
+
+## Thank you
+
+We appreciate everyone who invests time, energy, and expertise into Spectrum Web Components. Your contributions—big or small—help this library evolve to serve a broader audience and remain at a high standard of quality.
+
+If you have any suggestions for improving these guidelines, feel free to open a pull request or bring it up in our community discussions. We're always eager to make the contribution experience better.
+
+Happy contributing!

CONTRIBUTOR-DOCS/01_contributor-guides/02_using-the-issue-tracker.md

@@ -0,0 +1,69 @@
+<!-- Generated breadcrumbs - DO NOT EDIT -->
+
+[CONTRIBUTOR-DOCS](../README.md) / [Contributor guides](README.md) / Using the issue tracker
+
+<!-- Document title (editable) -->
+
+# Using the issue tracker
+
+<!-- Generated TOC - DO NOT EDIT -->
+
+<details open>
+<summary><strong>In this doc</strong></summary>
+
+- [Before creating a new issue](#before-creating-a-new-issue)
+- [Filing a bug report](#filing-a-bug-report)
+- [Classifying issue severity](#classifying-issue-severity)
+- [Requesting a feature or a new component](#requesting-a-feature-or-a-new-component)
+
+</details>
+
+<!-- Document content (editable) -->
+
+We use GitHub Issues for two purposes:
+
+1. Bug Reports
+2. Feature Requests (after initial discussion)
+
+If you're having a usage issue or need support, do not open an issue. Instead, reference the Community & Support section. This helps us keep issues focused on actual bugs and actionable tasks.
+
+## Before creating a new issue
+
+1. Check the [Open Issues](https://github.com/adobe/spectrum-web-components/issues) to see if the problem has already been reported.
+    - TIP: Apply the component label to make your search process more straightforward.
+2. If it has and the issue is still open, add a comment to the existing issue instead of opening a new one.
+3. Check if you can reproduce the problem in the latest version of Spectrum Web Components by forking a code example in [Stackblitz](https://stackblitz.com/orgs/custom/SWC-Team/collections/spectrum-web-components). 
+4. If there are no related open issues and it is reproducible in isolation, then open a [Bug Report](https://github.com/adobe/spectrum-web-components/issues/new?template=bug_report.yaml).
+
+## Filing a bug report
+
+When you file a bug, please use the `Bug Report` template provided in GitHub. Include the following information:
+
+- A concise summary of the problem.
+- Relevant components involved in the issue.
+- Issue Severity based on our classifications defined below.
+- What you expected vs. what actually happened, along with any errors logged in the console.
+- Steps to reproduce the issue, preferably in an isolated environment, so that we can narrow down where the bug is originating from, preferably by forking an example from our [Stackblitz project](https://stackblitz.com/orgs/custom/SWC-Team/collections/spectrum-web-components). Be detailed if you write out the steps!
+- Relevant environment details (OS, browser, library version).
+
+Clear bug reports speed up the triage process, help us replicate the issue, and keep the project robust.
+
+## Classifying issue severity
+
+Providing the correct issue severity classification helps us adequately assess and prioritize your issue. We reserve the right to adjust the severity of your bug during triage.
+Below is our issue severity classification criteria:
+
+| Severity level | Description                                                                                                                                                                                                                                                                                                                                                     | Examples                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 🔥 SEV 1       | A critical design or functionality issue that breaks the design system, causes significant usability problems, or exposes critical security vulnerabilities. This issue impacts all users and/or essential workflows, making users unable to complete any tasks. Requires immediate attention.                                                                  | Broken navigation system, complete unresponsiveness on all devices, components not rendering, inaccessible primary actions, security vulnerabilities.<br><br>Accessibility: The end user is not able to complete core tasks or activities (e.g., key navigational elements not accessible via keyboard, missing or incorrect form labels that prevent screen reader users from completing forms or actions, critical color contrast issues that prevent users from reading or interacting with essential content). |
+| 🔴 SEV 2       | A significant problem affecting the design, usability, or functionality of the system or components for a subset of users. This issue causes major disruptions and prevent users from completing tasks or workflows.<br><br>Accessibility: Does not conform with WCAG 2.1 Level AA criteria and blocks core user tasks (no known workaround).                   | Content that is out of view or unreachable by customers, critical buttons or links not functioning, or actions that cannot be submitted. Unintentional breaking changes causing disruptions in production environments.<br><br>Accessibility: Issue with a component or controller with widespread use and blocks core user tasks (no known workaround).                                                                                                                                                           |
+| 🟠 SEV 3       | A design or functionality issue that causes noticeable errors or minor usability problems for users which either cause confusion or degrade the user experience, but do not prevent task completion.<br><br>Accessibility: Does not conform with WCAG 2.1 Level AA criteria and is either non-blocking for core user tasks or blocking for non-core user tasks. | Misleading labels, inconsistent component behavior, unexpected interactions, decreases in system performance.<br><br>Accessibility: Workarounds are available and discoverable for the end user to complete core user tasks, or the end user is not able to complete non-core user tasks (e.g., inadequate ARIA labels, improper focus management, insufficient color contrast for non-critical elements).                                                                                                         |
+| 🟡 SEV 4       | A minor design flaw that affects user experience, but doesn't have a serious impact on overall usability or functionality. This issue does not prevent users from completing tasks.<br><br>Accessibility: Does not conform with WCAG 2.1 Level AA criteria but has lower user impact.                                                                           | Minor visual inconsistencies, non-critical content misalignment, or minor layout issues.<br><br>Accessibility: A WCAG violation is present in areas not frequently visited by end users, or it has a lower impact on overall accessibility and usability.                                                                                                                                                                                                                                                          |
+| 🟢 SEV 5       | A low-level design inconsistency or minor issue that slightly affects usability or aesthetics, with minimal impact on users.                                                                                                                                                                                                                                    | Slight color deviations, minor typographical errors, or small spacing inconsistencies that do not impact functionality.                                                                                                                                                                                                                                                                                                                                                                                            |
+
+## Requesting a feature or a new component
+
+Is there something you wish the project did differently? Have a new component in mind? We love hearing new ideas and are eager to collaborate!
+
+- Start with a discussion: Share your idea in Discussions to gather feedback and see if it aligns with project goals.
+- Open a feature request issue: After some positive initial conversation, open an issue using the `Feature Request` or `New Component` template with details and potential use cases.

CONTRIBUTOR-DOCS/01_contributor-guides/03_working-in-the-swc-repo.md

@@ -0,0 +1,147 @@
+<!-- Generated breadcrumbs - DO NOT EDIT -->
+
+[CONTRIBUTOR-DOCS](../README.md) / [Contributor guides](README.md) / Working in the SWC repo
+
+<!-- Document title (editable) -->
+
+# Working in the SWC repo
+
+<!-- Generated TOC - DO NOT EDIT -->
+
+<details open>
+<summary><strong>In this doc</strong></summary>
+
+- [About this guide](#about-this-guide)
+- [Getting started](#getting-started)
+    - [Prerequisites](#prerequisites)
+    - [Installation](#installation)
+- [Repository structure](#repository-structure)
+- [Development workflow](#development-workflow)
+    - [Developing](#developing)
+    - [Testing](#testing)
+    - [Linting](#linting)
+    - [Building](#building)
+- [Command reference](#command-reference)
+
+</details>
+
+<!-- Document content (editable) -->
+
+## About this guide
+
+This guide covers the essential information you need to work effectively in the Spectrum Web Components (SWC) repository.
+
+## Getting started
+
+### Prerequisites
+
+Before you begin, ensure you have the following installed:
+
+- **Node.js**: Version 20.10.0 or higher (check with `node --version`)
+- **Yarn**: Version 4.6.0 or higher (check with `yarn --version`)
+- **Git**: For version control (check with `git --version`)
+
+### Installation
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/adobe/spectrum-web-components.git
+```
+
+2. Install dependencies:
+
+```bash
+cd spectrum-web-components
+yarn install
+```
+
+## Repository structure
+
+SWC is currently in transition from its first generation (**1st-gen**) to its second generation (**2nd-gen**).
+
+> This transition is motivated by some important strategic goals. For more information, see [Objectives and Strategy](../03_project-planning/01_objectives-and-strategy.md).
+
+Instead of creating a separate branch or repo for 2nd-gen, we are working on the 1st-gen and 2nd-gen projects side-by-side in this repository, with some core functionality being shared between 1st- and 2nd-gen components. This strategy makes it easier for us to continue actively improving and supporting 1st-gen even as we devote much of our attention to defining and building 2nd-gen.
+
+Reflecting the side-by-side strategy, the repository is organized into two top-level workspaces:
+
+- **`1st-gen/`** contains all of the 1st-gen packages, tooling, and supporting materials.
+
+    Most of what lives here will be left behind in the transition to 2nd-gen; the core component functionality we'll carry forward is gradually being moved into the `2nd-gen` workspace.
+
+    While we'll continue doing work in `1st-gen` as needed to accomplish our goals, we expect this work to decrease steadily toward none.
+
+- **`2nd-gen/`** is a new workspace that we're building from the ground up to serve as a clean foundation for our future work. It includes:
+    - A Core library (`packages/core/`), which contains the functionality shared between 1st- and 2nd-gen
+
+    - The 2nd-gen SWC library (`packages/swc/`).
+
+During this transition, depending on what you're trying to accomplish, you may end up working in `1st-gen`, `2nd-gen`, or both. If you have any questions, [please ask](./01_getting-involved.md#community--support)—we're happy to help.
+
+## Development workflow
+
+The project's top-level `package.json` file defines [several commands](#command-reference) that can be run from the repository root, covering the most important parts of the development workflow.
+
+> By default, each command is run in both the 1st-gen and 2nd-gen workspaces, but you can add a `:1st-gen` or `:2nd-gen` suffix to any command to run it for only one workspace.
+
+### Developing
+
+We use Storybook to interact with and test components as we develop them, as well as to document components and demonstrate usage patterns for our customers. There are separate Storybooks for 1st- and 2nd-gen.
+
+**To start Storybook:**
+
+```bash
+yarn start
+```
+
+This command launches Storybook for both 1st- and 2nd-gen and opens a browser tab for each.
+
+### Testing
+
+**To run all tests:**
+
+```bash
+yarn test
+```
+
+### Linting
+
+The linter runs before each commit, but you can also run it manually.
+
+**To check for linting issues:**
+
+```bash
+yarn lint
+```
+
+### Building
+
+You should rarely need to trigger build explicitly, but you can do so as necessary.
+
+**To build all packages:**
+
+```bash
+yarn build
+```
+
+## Command reference
+
+Here are the most frequently used commands available from the repository root:
+
+| Command              | Description                                  |
+| -------------------- | -------------------------------------------- |
+| `yarn start`         | Start Storybook for both 1st-gen and 2nd-gen |
+| `yarn start:1st-gen` | Start Storybook for 1st-gen only             |
+| `yarn start:2nd-gen` | Start Storybook for 2nd-gen only             |
+| `yarn test`          | Run tests for both 1st-gen and 2nd-gen       |
+| `yarn test:1st-gen`  | Run tests for 1st-gen only                   |
+| `yarn test:2nd-gen`  | Run tests for 2nd-gen only                   |
+| `yarn lint`          | Check for linting issues (staged files)      |
+| `yarn lint:1st-gen`  | Check for linting issues in 1st-gen only     |
+| `yarn lint:2nd-gen`  | Check for linting issues in 2nd-gen only     |
+| `yarn build`         | Build all packages (2nd-gen then 1st-gen)    |
+| `yarn build:1st-gen` | Build 1st-gen packages only                  |
+| `yarn build:2nd-gen` | Build 2nd-gen packages only                  |
+
+For more specific workflows and advanced topics, refer to the other contributor guides.