docs: add contributor docs

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

@@ -0,0 +1,7 @@
+---
+description: Useful for updating auto-generated content in the contributor docs
+alwaysApply: false
+---
+If the user requests an update to the contributor docs (located in the CONTRIBUTOR_DOCS folder at the repository root), run the update process as described in the agent instructions within that folder.
+
+To locate the instructions, search for "ai-agent-instructions", or fall back to a recursive directory search if needed.

CONTRIBUTOR-DOCS/01_objectives-and-strategy.md

@@ -0,0 +1,114 @@
+<!-- Generated breadcrumbs - DO NOT EDIT -->
+
+[CONTRIBUTOR-DOCS](README.md) / Objectives and Strategy
+
+<!-- Document title (editable) -->
+
+# Objectives and Strategy
+
+<!-- Generated TOC - DO NOT EDIT -->
+
+<details open>
+<summary><strong>In this doc</strong></summary>
+
+- [Current Objectives](#current-objectives)
+    - [Unify Spectrum CSS & Spectrum Web Components](#unify-spectrum-css--spectrum-web-components)
+    - [Build a clean foundation for future work](#build-a-clean-foundation-for-future-work)
+    - [Enable Spectrum 2 adoption](#enable-spectrum-2-adoption)
+    - [Improve accessibility](#improve-accessibility)
+    - [Continually improve components](#continually-improve-components)
+- [Strategy](#strategy)
+    - [Disruptive vs. non-disruptive change](#disruptive-vs-non-disruptive-change)
+    - [Side-by-side development of 1st-gen and 2nd-gen](#side-by-side-development-of-1st-gen-and-2nd-gen)
+
+</details>
+
+<!-- Document content (editable) -->
+
+## Current Objectives
+
+The SWC project is currently focused on a relatively small set of strategic objectives:
+
+### Unify Spectrum CSS & Spectrum Web Components
+
+Integrate the formerly separate Spectrum CSS and SWC projects, forming a unified project with a single code base, delivering a single product that is laser-focused on the needs of our target customers.
+
+### Build a clean foundation for future work
+
+Improve tooling, infrastructure, and cross-cutting product layers:
+
+- Replace old, poorly supported tool chains and custom scripts with widely adopted, modern, turnkey solutions.
+
+- Simplify and improve our style-loading, theming, and customization capabilities.
+
+- Integrate and improve our documentation and Storybook.
+
+- Reduce complexity wherever possible.
+
+### Enable Spectrum 2 adoption
+
+Enable our customers to ship Spectrum-2-based products, working toward a full-fidelity Spectrum 2 implementation while making the path to Spectrum 2 adoption as smooth as possible for customers.
+
+This is a two-phase process:
+
+- **Phase 1:** Deliver a stable, production-quality Spectrum 2 implementation within our 1st-gen product, offering foundational S2 fidelity via the `spectrum-two` theme while avoiding breaking API and layout changes.
+
+    This phase is essentially complete, although some refinement of the `spectrum-two` theme continues.
+
+- **Phase 2:** Deliver a full-fidelity Spectrum 2 implementation as part of our 2nd-gen product.
+
+    This will entail some breaking changes, but to facilitate incremental migration on a view-by-view or component-by-component basis, it will be possible for customers to use 1st-gen and 2nd-gen SWC components together within a single project.
+
+### Improve accessibility
+
+Systematically improve accessibility by expanding documentation and examples, completing a comprehensive audit to address issues, and generally striving to maximize accessibility across all components.
+
+### Continually improve components
+
+Make improvements of all types and sizes to our components, including bug fixes, feature enhancements, improvements to API clarity and consistency, and major refactoring or replacement as needed.
+
+## Strategy
+
+From a value point of view, the objectives above are largely independent of one other. We want to keep them loosely coupled so that we can advance each according to its own priority, and so that work toward one objective doesn't needlessly block work toward another—for example, full-fidelity Spectrum 2 work shouldn't block accessibility work, and vice versa.
+
+At a high level, our strategy for efficiently pursuing our objectives in parallel is to:
+
+- Differentiate inherently disruptive changes from non-disruptive changes.
+
+- Channel disruptive changes into 2nd-gen, where we can take the time to get them right and the care to minimize the disruption they actually cause.
+
+- Work on 1st-gen and 2nd-gen side-by-side, so that non-disruptive changes can easily be shared between generations and delivered continually throughout the transition.
+
+### Disruptive vs. non-disruptive change
+
+Our first three objectives have aspects that are inherently disruptive, or have the potential to cause significant disruption—to the project, its customers, or both:
+
+- **Unifying Spectrum CSS and SWC** involves consolidating our work from two projects and repositories into one and making significant changes to the shape of our product offerings.
+
+- **Building a clean foundation for the future** entails making major changes to our workflows and tooling, the packages we ship, and cross-cutting product features like style-loading, theming and customization.
+
+- **Landing full-fidelity Spectrum 2 in SWC** will necessitate some breaking changes stemming from the design itself—changes to design tokens, and to the features, APIs and layout footprints of certain components.
+
+Meanwhile, most of the **accessibility improvements** and general **component improvements** we want to make aren't inherently disruptive—they can delivered in a continual stream of targeted, mostly non-breaking releases.
+
+### Side-by-side development of 1st-gen and 2nd-gen
+
+We have decided to work on 1st-gen and 2nd-gen side-by-side—in the same repository, but in separate workspaces. This gives us two important advantages: **isolation** and **colocation**.
+
+**Isolation** of 1st-gen and 2nd-gen in separate workspaces lets us build 2nd-gen iteratively from the ground up, leaving behind as much structural and technical debt as possible, without needing to worry about breaking 1st-gen. Disruptive changes are confined to the `second-gen` workspace, while the 1st-gen project continues working essentially "as-is."
+
+**Colocation** of 1st-gen and 2nd-gen in a single branch of the same repository makes it easy to share core component functionality between generations. Here's how this works:
+
+- We locate core component implementations in the 2nd-gen Core library as **abstract, non-rendering classes**.
+
+    These classes define **shared API** and implement **generation-agnostic behavior and logic**.
+
+- In both 1st-gen and 2nd-gen SWC, we implement components as **concrete, rendering classes** that extend from the abstract classes in Core.
+
+    These classes implement **generation-specific rendering and styling**, and **override API and behavior** as needed.
+
+This architecture delivers two key benefits:
+
+1. **Improvements we make in shared code immediately benefit 1st-gen SWC customers,** letting us deliver value on a continual basis throughout the transition.
+
+2. **Sharing code will help make customers' eventual migration from 1st-gen to 2nd-gen as smooth as possible.** By design, it will be difficult to introduce unnecessary or unintentional API or functional differences between 1st- and 2nd-gen components.

CONTRIBUTOR-DOCS/02_contributor-guides/01_code-of-conduct.md

@@ -0,0 +1,96 @@
+<!-- Generated breadcrumbs - DO NOT EDIT -->
+
+[CONTRIBUTOR-DOCS](../README.md) / [Contributor Guides](README.md) / Adobe Code of Conduct
+
+<!-- Document title (editable) -->
+
+# Adobe Code of Conduct
+
+<!-- Generated TOC - DO NOT EDIT -->
+
+<details open>
+<summary><strong>In this doc</strong></summary>
+
+- [Our Pledge](#our-pledge)
+- [Our Standards](#our-standards)
+- [Our Responsibilities](#our-responsibilities)
+- [Scope](#scope)
+- [Enforcement](#enforcement)
+- [Attribution](#attribution)
+
+</details>
+
+<!-- Document content (editable) -->
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to make participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+- The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise, unacceptable behavior may be
+reported by contacting the project team at Grp-opensourceoffice@adobe.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality concerning the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

CONTRIBUTOR-DOCS/02_contributor-guides/README.md

@@ -0,0 +1,22 @@
+<!-- Generated breadcrumbs - DO NOT EDIT -->
+
+[CONTRIBUTOR-DOCS](../README.md) / Contributor Guides
+
+<!-- Document title (editable) -->
+
+# Contributor Guides
+
+<!-- Generated TOC - DO NOT EDIT -->
+
+<details open>
+<summary><strong>Beneath this doc</strong></summary>
+
+- [Adobe Code of Conduct](01_code-of-conduct.md)
+- [Authoring contributor docs](authoring-contributor-docs/README.md)
+    - [AI agent instructions](authoring-contributor-docs/01_ai-agent-instructions.md)
+
+</details>
+
+<!-- Document content (editable) -->
+
+(Content to be added)