diff --git a/.cursor/rules/contributor-doc-update.mdc b/.cursor/rules/contributor-doc-update.mdc
new file mode 100644
index 00000000000..dbcb17def6e
--- /dev/null
+++ b/.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.
\ No newline at end of file
diff --git a/CONTRIBUTOR-DOCS/01_objectives-and-strategy.md b/CONTRIBUTOR-DOCS/01_objectives-and-strategy.md
new file mode 100644
index 00000000000..f088221663b
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/01_objectives-and-strategy.md
@@ -0,0 +1,114 @@
+
+
+[CONTRIBUTOR-DOCS](README.md) / Objectives and Strategy
+
+
+
+# Objectives and Strategy
+
+
+
+
+In this doc
+
+- [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)
+
+
+
+
+
+## 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.
diff --git a/CONTRIBUTOR-DOCS/02_contributor-guides/01_code-of-conduct.md b/CONTRIBUTOR-DOCS/02_contributor-guides/01_code-of-conduct.md
new file mode 100644
index 00000000000..2730af937d7
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/02_contributor-guides/01_code-of-conduct.md
@@ -0,0 +1,96 @@
+
+
+[CONTRIBUTOR-DOCS](../README.md) / [Contributor Guides](README.md) / Adobe Code of Conduct
+
+
+
+# Adobe Code of Conduct
+
+
+
+
+In this doc
+
+- [Our Pledge](#our-pledge)
+- [Our Standards](#our-standards)
+- [Our Responsibilities](#our-responsibilities)
+- [Scope](#scope)
+- [Enforcement](#enforcement)
+- [Attribution](#attribution)
+
+
+
+
+
+## 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/
diff --git a/CONTRIBUTOR-DOCS/02_contributor-guides/README.md b/CONTRIBUTOR-DOCS/02_contributor-guides/README.md
new file mode 100644
index 00000000000..87172897f54
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/02_contributor-guides/README.md
@@ -0,0 +1,22 @@
+
+
+[CONTRIBUTOR-DOCS](../README.md) / Contributor Guides
+
+
+
+# Contributor Guides
+
+
+
+
+Beneath this doc
+
+- [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)
+
+
+
+
+
+(Content to be added)
diff --git a/CONTRIBUTOR-DOCS/02_contributor-guides/authoring-contributor-docs/01_ai-agent-instructions.md b/CONTRIBUTOR-DOCS/02_contributor-guides/authoring-contributor-docs/01_ai-agent-instructions.md
new file mode 100644
index 00000000000..c333f2e71cd
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/02_contributor-guides/authoring-contributor-docs/01_ai-agent-instructions.md
@@ -0,0 +1,306 @@
+
+
+[CONTRIBUTOR-DOCS](../../README.md) / [Contributor Guides](../README.md) / [Authoring contributor docs](README.md) / AI agent instructions
+
+
+
+# AI agent instructions
+
+
+
+
+In this doc
+
+- [Role 1: Operator](#role-1-operator)
+ - [When to run](#when-to-run)
+ - [How to run](#how-to-run)
+ - [Responsibilities](#responsibilities)
+ - [Debugging errors](#debugging-errors)
+ - [Debugging output issues](#debugging-output-issues)
+ - [Verifying links](#verifying-links)
+- [Role 2: Maintainer](#role-2-maintainer)
+ - [Requirements and specifications](#requirements-and-specifications)
+ - [When to maintain](#when-to-maintain)
+ - [Maintenance process](#maintenance-process)
+ - [Script architecture](#script-architecture)
+- [Script behavior details](#script-behavior-details)
+ - [What the script does](#what-the-script-does)
+ - [Breadcrumb format](#breadcrumb-format)
+ - [TOC format](#toc-format)
+ - [Display name derivation](#display-name-derivation)
+- [Testing checklist](#testing-checklist)
+
+
+
+
+
+This document defines two distinct roles for AI agents working with the CONTRIBUTOR-DOCS navigation system.
+
+## Role 1: Operator
+
+Run the regeneration script to update breadcrumbs and TOCs.
+
+### When to run
+
+Execute the script when:
+
+- A file or folder is added, removed, or renamed
+- A file is moved to a different location
+- Document H1 headings are changed (these become display names)
+- Document H2/H3 headings are added, removed, or changed
+- The folder structure changes
+- A human maintainer or another AI agent requests it
+
+### How to run
+
+```bash
+cd CONTRIBUTOR-DOCS/02_contributor-guides/authoring-contributor-docs
+node update-nav.js
+```
+
+**Expected time:** ~15-20ms for entire CONTRIBUTOR-DOCS tree
+
+### Responsibilities
+
+1. **Execute** the script with appropriate parameters
+2. **Verify success** - check that the script completed without errors
+3. **Report results** - show the output summary (files updated, time taken)
+4. **Debug if needed** - if errors occur, investigate and fix or report to the user
+
+### Debugging errors
+
+If the script fails:
+
+1. **Check the error message** - the script provides clear error output
+2. **Verify file structure** - ensure all markdown files have the `` marker
+3. **Check file permissions** - ensure files are writable
+4. **Validate markdown** - ensure H1 headings use proper syntax (`# Title`, not `##`)
+5. **Report to user** - if you can't resolve, explain what you found
+
+### Debugging output issues
+
+When the auto-generated navigation appears incorrect or malformed:
+
+1. **First, investigate the script** - Check if the issue can be fixed by updating `update-nav.js`
+ - Read the script to understand how it processes the problematic content
+ - Look for edge cases or patterns it doesn't handle correctly
+ - Consider whether a fix to the script would allow the current document structure to work
+
+2. **Only suggest content changes as a last resort** - Don't immediately suggest modifying document content
+ - Document authors may have good reasons for their structure choices
+ - Script improvements benefit all documents, not just one
+ - Content changes may limit what authors can express in their docs
+
+3. **Example**: If headings with links generate malformed TOC entries:
+ - ✅ Good: Investigate the script's heading extraction, find it doesn't strip link syntax, add a fix
+ - ❌ Bad: Tell the user to remove links from their headings
+
+**Philosophy:** The script should adapt to reasonable document structures, not the other way around.
+
+### Verifying links
+
+Link verification takes significantly longer than nav regeneration (~40-50 seconds vs. ~15ms). **Only perform link verification when explicitly requested by a maintainer.**
+
+**How to verify links:**
+
+**Inter-document links** (links between files):
+
+1. Search for relative links to other markdown files: `\]\([^\)]*\.md\)`
+2. For each link found in document content (not auto-generated navigation):
+ - Verify the target file exists at the specified path
+ - Confirm the relative path is correct from the source file's location
+
+**Internal anchor links** (links to section headings):
+
+1. Search for anchor links within the same document: `\]\(#[a-z0-9-]+\)`
+2. Search for anchor links to other documents: `\]\([^\)]*\.md#[a-z0-9-]+\)`
+3. For each anchor link found in document content (not auto-generated TOCs):
+ - Extract the heading anchor (e.g., `#current-objectives`)
+ - Search for the corresponding heading in the target document
+ - Verify the heading exists and the anchor matches GitHub's anchor format:
+ - Lowercase all text
+ - Replace spaces with hyphens
+ - Remove special characters except hyphens
+ - Example: `## Current Objectives` → `#current-objectives`
+
+**Report findings:**
+
+- List all manually authored links found
+- Confirm which links are valid
+- Report any broken links with specific details about what's missing or incorrect
+
+---
+
+## Role 2: Maintainer
+
+Review and update the regeneration script when requirements or specifications change.
+
+### Requirements and specifications
+
+The script's behavior is defined by:
+
+1. **Human maintainer instructions** (`human-maintainer-instructions.md`)
+ - File and folder naming conventions
+ - Numbering rules
+ - Document structure requirements
+ - Display name derivation rules
+
+2. **File structure conventions** (implicit in the codebase)
+ - README.md files as folder overviews
+ - Lowercase kebab-case naming
+ - Optional sequential numbering
+ - HTML comment markers for separating content
+
+3. **Output format requirements**
+ - Breadcrumb format and linking rules
+ - TOC structure ("In this doc" and "Beneath this doc" sections)
+ - Collapsible `` elements
+ - GitHub-style anchor links
+
+### When to maintain
+
+Update the script when:
+
+- Naming or numbering conventions change
+- Breadcrumb or TOC format requirements change
+- New edge cases are discovered
+- Display name derivation rules change
+- File structure conventions evolve
+- Performance optimizations are needed
+
+### Maintenance process
+
+1. **Review the change request**
+ - Understand what requirement or specification has changed
+ - Identify which part of the script needs updating
+
+2. **Update the script** (`update-nav.js`)
+ - Modify the relevant functions
+ - Maintain code quality and comments
+ - Preserve existing functionality where applicable
+
+3. **Test thoroughly**
+ - Run the script on the entire CONTRIBUTOR-DOCS tree
+ - Verify output matches new requirements
+ - Check that existing functionality still works
+ - Spot-check several files manually
+
+4. **Update documentation**
+ - Update this file if the operator role changes
+ - Update human maintainer instructions if conventions change
+ - Add comments in the script explaining non-obvious logic
+
+5. **Report changes**
+ - Summarize what was changed and why
+ - Note any breaking changes or new behaviors
+ - Provide examples of the new output format
+
+### Script architecture
+
+The script (`update-nav.js`) is organized into several sections:
+
+1. **Configuration** - Constants for markers and behavior settings
+2. **Utility Functions** - Helper functions for text processing and code block detection
+3. **Metadata Extraction** - Scans the documentation tree and builds relationships
+4. **Navigation Generation** - Creates breadcrumbs and table of contents
+5. **File Update** - Replaces auto-generated content while preserving manual edits
+
+For implementation details, see the script source code which includes inline comments explaining the logic.
+
+---
+
+## Script behavior details
+
+### What the script does
+
+**Step 1: Extract metadata** (~10-15ms)
+
+- Walks the entire documentation tree
+- Extracts H1 headings (used as display names)
+- Extracts H2/H3 headings (for "In this doc" TOC section)
+- Maps parent-child relationships
+- Identifies folders with/without README files
+
+**Step 2: Generate navigation** (~2-4ms)
+For each file:
+
+- Creates breadcrumbs linking to parent READMEs
+- Creates "In this doc" TOC from H2/H3 headings
+- Creates "Beneath this doc" TOC from child files/folders
+- Wraps TOC in collapsible `` element
+
+**Step 3: Update files** (~2-4ms)
+
+- Finds `` marker
+- Replaces everything above it with new breadcrumbs and TOC
+- Preserves all content below the marker
+- Handles edge cases (duplicate markers in code blocks)
+
+### Breadcrumb format
+
+```markdown
+[ROOT](../../README.md) / [Parent](../README.md) / Current Page
+```
+
+**Rules:**
+
+- Root is always `CONTRIBUTOR-DOCS` linking to root README.md
+- Parent folders link to their README.md (if it exists)
+- Folders without README show as plain text (no link)
+- Current page is plain text (not linked)
+- Display names from H1 headings, not filenames
+
+### TOC format
+
+```markdown
+
+Contents
+
+- **In this doc**
+ - [Section heading](#section-heading)
+- **Beneath this doc**
+ - [Child file](./child.md)
+ - [Child folder](./folder/README.md)
+
+
+```
+
+**Rules:**
+
+- Omit "In this doc" if no H2/H3 headings exist
+- Omit "Beneath this doc" if no child files/folders exist
+- Omit entire TOC if both sections would be empty
+- Use GitHub-style anchors (lowercase, hyphens, no special chars)
+- Recursively include grandchildren with proper indentation
+
+### Display name derivation
+
+**For files:** Extract H1 heading
+
+- `# Migration Status` → "Migration Status"
+
+**For folders with README:** Extract H1 from README.md
+
+- README contains `# Workstream Info` → "Workstream Info"
+
+**For folders without README:** Derive from folder name
+
+1. Remove number prefix: `04_workstream-info` → `workstream-info`
+2. Replace hyphens with spaces: `workstream-info` → `workstream info`
+3. Apply title case: `workstream info` → `Workstream Info`
+
+---
+
+## Testing checklist
+
+After running or modifying the script:
+
+- [ ] Script completed without errors
+- [ ] All files were updated (check the count in output)
+- [ ] Spot-check breadcrumbs are correct and links work
+- [ ] Spot-check TOCs reflect current structure
+- [ ] Display names are human-readable (from H1 headings)
+- [ ] Folders without README show as plain text (no link)
+- [ ] Collapsible TOC sections work properly
+- [ ] Manual content below `` is preserved
+- [ ] No trailing spaces or formatting issues
diff --git a/CONTRIBUTOR-DOCS/02_contributor-guides/authoring-contributor-docs/README.md b/CONTRIBUTOR-DOCS/02_contributor-guides/authoring-contributor-docs/README.md
new file mode 100644
index 00000000000..efb4ede81de
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/02_contributor-guides/authoring-contributor-docs/README.md
@@ -0,0 +1,178 @@
+
+
+[CONTRIBUTOR-DOCS](../../README.md) / [Contributor Guides](../README.md) / Authoring contributor docs
+
+
+
+# Authoring contributor docs
+
+
+
+
+In this doc
+
+- [Overview](#overview)
+- [Writing & editing docs](#writing--editing-docs)
+ - [Creating a new doc](#creating-a-new-doc)
+ - [Editing existing docs](#editing-existing-docs)
+ - [Titles and headings](#titles-and-headings)
+ - [Links](#links)
+- [Organizing docs](#organizing-docs)
+ - [Folder structure](#folder-structure)
+ - [Use `README.md` for index files](#use-readmemd-for-index-files)
+ - [File and folder naming conventions](#file-and-folder-naming-conventions)
+ - [Ordering](#ordering)
+- [Updating auto-generated navigation](#updating-auto-generated-navigation)
+ - [Verifying and troubleshooting](#verifying-and-troubleshooting)
+- [Committing updates](#committing-updates)
+
+
+
+
+Beneath this doc
+
+- [AI agent instructions](01_ai-agent-instructions.md)
+
+
+
+
+
+## Overview
+
+This document provides guidance for maintainers of the Spectrum Web Components contributor docs, which are located in the CONTRIBUTOR_DOCS folder at the root of the repository.
+
+For the most part, the contributor docs are just ordinary Markdown (`.md`) files located in a nested folder structure.
+
+The navigational structure of the docs is derived from the location of the files within the folder structure and the Markdown headings within each doc.
+
+To help with browsability and navigation:
+
+- There are some conventions around file organization and naming (described in this document).
+- There is a script that automatically [generates / updates breadcrumbs and TOCs](#updating-auto-generated-navigation).
+
+ You can run this script manually, but we recommend invoking it via an AI agent, so that the agent can help with verification and troubleshooting as needed.
+
+## Writing & editing docs
+
+### Creating a new doc
+
+To create a new doc, just decide where you want to put it (see [Organizing docs](#organizing-docs)), then write a standard Markdown file. This file should contain an H1 heading representing the document title, along with whatever content you want to include.
+
+```markdown
+# Your Document Title
+
+Your content goes here.
+
+## Section One
+
+More content...
+```
+
+You should not include navigational elements (breadcrumbs and TOCs), as these are [auto-generated and updated](#updating-auto-generated-navigation) upon request.
+
+### Editing existing docs
+
+When you are editing existing docs, you'll find [auto-generated breadcrumbs and TOCs](#updating-auto-generated-navigation) alongside the document content.
+
+Each doc file has the following structure, with markers clearly separating auto-generated and editable content:
+
+```markdown
+
+
+[Auto-generated breadcrumb navigation]
+
+
+
+# Your Document Title
+
+
+
+[Auto-generated table of contents]
+
+
+
+[Document content]
+```
+
+**What's editable:**
+
+- The H1 title (between `` and the TOC marker)
+- All content after ``
+
+### Titles and headings
+
+- As noted previously, each document should have a title, represented by a Markdown H1 (`#`) heading.
+
+ This title is displayed in the document, and used in generated breadcrumbs and TOCs.
+
+- Within each document, use proper heading hierarchy (don't skip levels).
+- Avoid duplicate heading names in the same document (they'll create conflicting anchor links in the TOC).
+
+### Links
+
+- When linking to other doc files, use relative links
+- Always link to files, not folders:
+ - Correct: `[Workstream Info](./04_workstream-info/README.md)`
+ - Incorrect: `[Workstream Info](./04_workstream-info/)`
+
+## Organizing docs
+
+### Folder structure
+
+- Keep the hierarchy shallow when possible (avoid deeply nested structures)
+- Group related content into folders
+
+### Use `README.md` for index files
+
+- Although not required, it often makes sense for a folder to have a "main" (index) file. The index file:
+ - Serves as a standard place to include overview content for a section of the docs
+ - Lets a folder appear as a clickable link in breadcrumbs and TOCs.
+
+- Naming a file `README.md` makes it the index file for the containing folder.
+
+ _We borrow this convention from GitHub, so you'll see the content when navigating to a folder in the GitHub UI._
+
+- If a folder doesn't contain a `README.md` file, the folder name will appear as plain text (no link) in breadcrumbs and TOCs.
+
+### File and folder naming conventions
+
+- File and folder names don't matter very much, since titles are taken from the H1 headings in Markdown files.
+- There are two ways in which file and folder names DO matter:
+ - File and folder names determine the order of TOC entries (see **Ordering**, below).
+ - In breadcrumbs and TOCs, the display name of a folder without a `README.md` file is derived from the folder's name.
+- By convention:
+ - Use lowercase kebab-case for all file and folder names: `2nd-gen-component-migration`.
+ - Exception: `README.md` files use conventional capitalization
+ - See **Ordering** for numbering conventions.
+
+### Ordering
+
+- Within each section of the auto-generated TOC, entries are ordered alphanumerically.
+- If the order of entries in a given section doesn't matter, there's no need to do anything special; entries will end up in alphabetical order by default.
+- Where needed, use numeric prefixes in your file and folder names to specify ordering.
+ - Numeric prefixes should be two digits, with leading zeros as needed, and followed by an underscore: `01_important-first.md`, `02_next.md`, etc.
+
+## Updating auto-generated navigation
+
+Request generation of breadcrumbs and TOC when you:
+
+- Add, remove, or rename a file or folder
+- Move a file to a different location
+- Add, remove, or rename section headings in a document
+- Change the organizational structure
+
+You can request an update by asking an AI Agent, pointing it to the [AI Agent Instructions](./01_ai-agent-instructions.md).
+
+> If you're using Cursor, you can just ask an agent to "update the contributor docs"; a project-level Cursor rule will help the agent find the applicable instructions.
+
+> If you don't have access to an AI Agent or prefer not to use one, you can also run the script manually. See [the AI Agent Instructions](./01_ai-agent-instructions.md) for details.
+
+### Verifying and troubleshooting
+
+The logic for generating navigational elements is quite simple, so it's unlikely that things will go wrong, but it's a good idea to do a quick spot-check to ensure that breadcrumbs and TOCs look correct, especially in areas of the docs that you have edited.
+
+If you encounter any issues, try asking an AI agent to help you troubleshoot, pointing the agent to the [AI Agent Instructions](./01_ai-agent-instructions.md).
+
+## Committing updates
+
+Because auto-generated navigation lives in the source files alongside manually edited content, you should [update the navigation](#updating-auto-generated-navigation) before committing any edits. This ensures that, at any given point in the commit history, the navigation will match the content in the docs.
diff --git a/CONTRIBUTOR-DOCS/02_contributor-guides/authoring-contributor-docs/update-nav.js b/CONTRIBUTOR-DOCS/02_contributor-guides/authoring-contributor-docs/update-nav.js
new file mode 100644
index 00000000000..771f30949e6
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/02_contributor-guides/authoring-contributor-docs/update-nav.js
@@ -0,0 +1,662 @@
+#!/usr/bin/env node
+
+/**
+ * Regenerate breadcrumbs and table of contents for all CONTRIBUTOR-DOCS files.
+ *
+ * Usage:
+ * node regenerate-nav.js [docs-root-path]
+ *
+ * Example:
+ * node regenerate-nav.js ../../
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ============================================================================
+// MARKER CONSTANTS
+// ============================================================================
+
+const MARKER_BREADCRUMBS = '';
+const MARKER_TITLE = '';
+const MARKER_TOC = '';
+const MARKER_CONTENT = '';
+
+// ============================================================================
+// CONFIGURATION
+// ============================================================================
+
+// Maximum depth for "Beneath this doc" navigation (number of indentation levels)
+// 1 = show only direct children (no indentation)
+// 2 = show children and grandchildren (one level of indentation)
+// 3 = show children, grandchildren, and great-grandchildren (two levels of indentation)
+const MAX_BENEATH_DOC_DEPTH = 2;
+
+// ============================================================================
+// UTILITY FUNCTIONS
+// ============================================================================
+
+function extractH1(filepath) {
+ try {
+ const content = fs.readFileSync(filepath, 'utf-8');
+ // Extract H1 from between title marker and TOC marker
+ const titlePos = findMarkerPosition(content, MARKER_TITLE);
+ if (titlePos === -1) {
+ // No markers, read from entire file
+ const match = content.match(/^#\s+(.+)$/m);
+ return match ? match[1].trim() : '';
+ }
+
+ const tocPos = findMarkerPosition(content, MARKER_TOC);
+ const startPos = titlePos + MARKER_TITLE.length;
+ const searchContent =
+ tocPos !== -1
+ ? content.substring(startPos, tocPos)
+ : content.substring(startPos);
+
+ const match = searchContent.match(/^#\s+(.+)$/m);
+ return match ? match[1].trim() : '';
+ } catch (err) {
+ return '';
+ }
+}
+
+function extractHeadings(filepath) {
+ try {
+ const content = fs.readFileSync(filepath, 'utf-8');
+ // Extract headings from document content (after content marker)
+ const contentPos = findMarkerPosition(content, MARKER_CONTENT);
+
+ let docContent;
+ if (contentPos !== -1) {
+ docContent = content.substring(contentPos + MARKER_CONTENT.length);
+ } else {
+ // No marker found, read entire file
+ docContent = content;
+ }
+
+ // Find all code block regions to exclude from heading extraction
+ const codeBlockRanges = findCodeBlockRanges(docContent);
+
+ // Extract headings, excluding those in code blocks
+ const headingMatches = [...docContent.matchAll(/^(#{2,3})\s+(.+)$/gm)];
+ return headingMatches
+ .filter((m) => {
+ // Check if this heading is inside a code block
+ const headingPos = m.index;
+ return !codeBlockRanges.some(
+ (range) =>
+ headingPos >= range.start && headingPos < range.end
+ );
+ })
+ .map((m) => {
+ const rawText = m[2].trim();
+ const cleanText = stripMarkdownLinks(rawText);
+ return {
+ level: m[1].length,
+ text: cleanText,
+ anchor: makeAnchor(cleanText),
+ };
+ });
+ } catch (err) {
+ return [];
+ }
+}
+
+function makeAnchor(text) {
+ return text
+ .toLowerCase()
+ .replace(/\s+/g, '-')
+ .replace(/[^a-z0-9\-]/g, '');
+}
+
+function stripMarkdownLinks(text) {
+ // Replace [link text](url) with just "link text"
+ return text.replace(/\[([^\]]+)\]\([^)]+\)/g, '$1');
+}
+
+function findCodeBlockRanges(content) {
+ // Find all code block regions (fenced code blocks: ```...```)
+ const codeBlockRanges = [];
+ const fencedBlockRegex = /^```[\s\S]*?^```/gm;
+ let match;
+ while ((match = fencedBlockRegex.exec(content)) !== null) {
+ codeBlockRanges.push({
+ start: match.index,
+ end: match.index + match[0].length,
+ });
+ }
+ return codeBlockRanges;
+}
+
+function findMarkerPosition(content, marker) {
+ // Find marker position, excluding those inside code blocks
+ const codeBlockRanges = findCodeBlockRanges(content);
+ let pos = 0;
+
+ while (true) {
+ pos = content.indexOf(marker, pos);
+ if (pos === -1) {
+ return -1; // Marker not found
+ }
+
+ // Check if this position is inside a code block
+ const inCodeBlock = codeBlockRanges.some(
+ (range) => pos >= range.start && pos < range.end
+ );
+
+ if (!inCodeBlock) {
+ return pos; // Found marker outside code blocks
+ }
+
+ // This occurrence is in a code block, keep searching
+ pos += marker.length;
+ }
+}
+
+function deriveName(name) {
+ return name
+ .replace(/^\d+_/, '')
+ .replace(/\.(md|js|ts|json)$/, '')
+ .replace(/-/g, ' ')
+ .split(' ')
+ .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+ .join(' ');
+}
+
+// ============================================================================
+// METADATA EXTRACTION
+// ============================================================================
+
+function walkTree(dir, baseDir = dir, parentPath = null) {
+ const result = { files: {}, folders: {} };
+ const relativePath = parentPath || '.';
+
+ const items = fs
+ .readdirSync(dir, { withFileTypes: true })
+ .filter(
+ (item) => !item.name.startsWith('.') && item.name !== 'node_modules'
+ )
+ .sort((a, b) => a.name.localeCompare(b.name, 'en', { numeric: true }));
+
+ const children = items.map((item) => item.name);
+
+ for (const item of items) {
+ const fullPath = path.join(dir, item.name);
+ const itemRelativePath = path.join(relativePath, item.name);
+
+ if (item.isDirectory()) {
+ const hasReadme = fs.existsSync(path.join(fullPath, 'README.md'));
+ const readmeH1 = hasReadme
+ ? extractH1(path.join(fullPath, 'README.md'))
+ : '';
+
+ result.folders[itemRelativePath] = {
+ name: item.name,
+ hasReadme,
+ displayName: hasReadme ? readmeH1 : deriveName(item.name),
+ parent: relativePath,
+ children: fs
+ .readdirSync(fullPath)
+ .filter((f) => !f.startsWith('.') && f !== 'node_modules')
+ .sort((a, b) =>
+ a.localeCompare(b, 'en', { numeric: true })
+ ),
+ };
+
+ const subResult = walkTree(fullPath, baseDir, itemRelativePath);
+ Object.assign(result.files, subResult.files);
+ Object.assign(result.folders, subResult.folders);
+ } else if (item.name.endsWith('.md')) {
+ const h1 = extractH1(fullPath);
+ const headings = extractHeadings(fullPath);
+
+ result.files[itemRelativePath] = {
+ name: item.name,
+ displayName: h1 || deriveName(item.name),
+ parent: relativePath,
+ headings,
+ isReadme: item.name === 'README.md',
+ fullPath,
+ };
+ }
+ }
+
+ if (relativePath === '.') {
+ result.folders['.'] = {
+ name: path.basename(dir),
+ hasReadme: fs.existsSync(path.join(dir, 'README.md')),
+ displayName: 'CONTRIBUTOR-DOCS',
+ parent: null,
+ children,
+ };
+ }
+
+ return result;
+}
+
+// ============================================================================
+// BREADCRUMB GENERATION
+// ============================================================================
+
+function generateBreadcrumb(filePath, metadata) {
+ const fileMeta = metadata.files[filePath];
+ if (!fileMeta) return '';
+
+ // Root README has no breadcrumb
+ if (filePath === './README.md' || filePath === 'README.md') {
+ return '';
+ }
+
+ const segments = [];
+ let currentPath = fileMeta.parent;
+ const isReadme = fileMeta.isReadme;
+
+ // Walk up parent chain
+ while (currentPath && currentPath !== '.') {
+ const folderMeta = metadata.folders[currentPath];
+ if (!folderMeta) break;
+
+ const hasReadme = folderMeta.hasReadme;
+
+ // If current file is a README in this folder, skip this folder in breadcrumb
+ // (we don't want "Folder / Folder" where both refer to the same README)
+ if (
+ isReadme &&
+ hasReadme &&
+ path.join(currentPath, 'README.md') === filePath
+ ) {
+ currentPath = folderMeta.parent;
+ continue;
+ }
+
+ const relPath = path.relative(
+ path.dirname(filePath),
+ hasReadme ? path.join(currentPath, 'README.md') : currentPath
+ );
+
+ segments.unshift({
+ name: folderMeta.displayName,
+ link: hasReadme ? relPath : null,
+ });
+
+ currentPath = folderMeta.parent;
+ }
+
+ // Add root
+ const rootRelPath = path.relative(path.dirname(filePath), './README.md');
+ segments.unshift({ name: 'CONTRIBUTOR-DOCS', link: rootRelPath });
+
+ // Add current page (no link)
+ segments.push({ name: fileMeta.displayName, link: null });
+
+ // Compose breadcrumb
+ return segments
+ .map((seg) => (seg.link ? `[${seg.name}](${seg.link})` : seg.name))
+ .join(' / ');
+}
+
+// ============================================================================
+// TOC GENERATION
+// ============================================================================
+
+function generateTOC(filePath, metadata) {
+ const fileMeta = metadata.files[filePath];
+ if (!fileMeta) return '';
+
+ const sections = [];
+
+ // "In this doc" section
+ if (fileMeta.headings && fileMeta.headings.length > 0) {
+ const lines = [
+ '',
+ 'In this doc',
+ '',
+ ];
+ for (const heading of fileMeta.headings) {
+ const indent = ' '.repeat(heading.level - 2); // H2 = no indent, H3 = 4 spaces
+ lines.push(`${indent}- [${heading.text}](#${heading.anchor})`);
+ }
+ lines.push('', '');
+ sections.push(lines.join('\n'));
+ }
+
+ // "Beneath this doc" section
+ const beneathLines = generateBeneathDoc(filePath, metadata, 0, 1);
+ if (beneathLines) {
+ const lines = [
+ '',
+ 'Beneath this doc',
+ '',
+ ];
+ lines.push(beneathLines);
+ lines.push('', '');
+ sections.push(lines.join('\n'));
+ }
+
+ if (sections.length === 0) {
+ return ''; // No TOC needed
+ }
+
+ return sections.join('\n\n');
+}
+
+function generateBeneathDoc(filePath, metadata, indentLevel, depth) {
+ const fileMeta = metadata.files[filePath];
+
+ // Only README files can have "beneath this doc" content
+ // Regular files are leaf nodes and don't have children
+ if (!fileMeta.isReadme) {
+ return null;
+ }
+
+ const parentFolder = fileMeta.parent;
+ const folderMeta = metadata.folders[parentFolder];
+
+ if (
+ !folderMeta ||
+ !folderMeta.children ||
+ folderMeta.children.length === 0
+ ) {
+ return null;
+ }
+
+ const lines = [];
+ const indent = ' '.repeat(indentLevel);
+
+ for (const childName of folderMeta.children) {
+ const childPath = path
+ .join(parentFolder, childName)
+ .replace(/\\/g, '/');
+
+ // Check if it's a file
+ if (metadata.files[childPath]) {
+ const childFileMeta = metadata.files[childPath];
+ // Skip self (the README file)
+ if (childPath === filePath) continue;
+
+ const relPath = path.relative(path.dirname(filePath), childPath);
+ lines.push(`${indent}- [${childFileMeta.displayName}](${relPath})`);
+
+ // Check if it's a folder
+ } else if (metadata.folders[childPath]) {
+ const childFolderMeta = metadata.folders[childPath];
+
+ if (childFolderMeta.hasReadme) {
+ const readmePath = path.join(childPath, 'README.md');
+ const relPath = path.relative(
+ path.dirname(filePath),
+ readmePath
+ );
+ lines.push(
+ `${indent}- [${childFolderMeta.displayName}](${relPath})`
+ );
+ } else {
+ // No README, show as plain text
+ lines.push(`${indent}- ${childFolderMeta.displayName}`);
+ }
+
+ // Recursively add grandchildren if we haven't hit the depth limit
+ if (depth < MAX_BENEATH_DOC_DEPTH) {
+ const grandchildren = generateGrandchildren(
+ childPath,
+ filePath,
+ metadata,
+ indentLevel + 1,
+ depth + 1
+ );
+ if (grandchildren) {
+ lines.push(grandchildren);
+ }
+ }
+ }
+ }
+
+ return lines.length > 0 ? lines.join('\n') : null;
+}
+
+function generateGrandchildren(
+ folderPath,
+ originFilePath,
+ metadata,
+ indentLevel,
+ depth
+) {
+ const folderMeta = metadata.folders[folderPath];
+ if (
+ !folderMeta ||
+ !folderMeta.children ||
+ folderMeta.children.length === 0
+ ) {
+ return null;
+ }
+
+ const lines = [];
+ const indent = ' '.repeat(indentLevel);
+
+ for (const childName of folderMeta.children) {
+ const childPath = path.join(folderPath, childName).replace(/\\/g, '/');
+
+ // Check if it's a file
+ if (metadata.files[childPath]) {
+ const childFileMeta = metadata.files[childPath];
+ // Skip README in the folder itself (already linked from parent)
+ if (childName === 'README.md') continue;
+
+ const relPath = path.relative(
+ path.dirname(originFilePath),
+ childPath
+ );
+ lines.push(`${indent}- [${childFileMeta.displayName}](${relPath})`);
+
+ // Check if it's a folder
+ } else if (metadata.folders[childPath]) {
+ const childFolderMeta = metadata.folders[childPath];
+
+ if (childFolderMeta.hasReadme) {
+ const readmePath = path.join(childPath, 'README.md');
+ const relPath = path.relative(
+ path.dirname(originFilePath),
+ readmePath
+ );
+ lines.push(
+ `${indent}- [${childFolderMeta.displayName}](${relPath})`
+ );
+ } else {
+ // No README, show as plain text
+ lines.push(`${indent}- ${childFolderMeta.displayName}`);
+ }
+
+ // Recursively add great-grandchildren if we haven't hit the depth limit
+ if (depth < MAX_BENEATH_DOC_DEPTH) {
+ const descendants = generateGrandchildren(
+ childPath,
+ originFilePath,
+ metadata,
+ indentLevel + 1,
+ depth + 1
+ );
+ if (descendants) {
+ lines.push(descendants);
+ }
+ }
+ }
+ }
+
+ return lines.length > 0 ? lines.join('\n') : null;
+}
+
+// ============================================================================
+// FILE UPDATE
+// ============================================================================
+
+function updateFile(filePath, metadata, docsRoot) {
+ const fileMeta = metadata.files[filePath];
+ if (!fileMeta) return false;
+
+ const fullPath = fileMeta.fullPath;
+
+ try {
+ const content = fs.readFileSync(fullPath, 'utf-8');
+
+ // Check for markers (ignoring those in code blocks)
+ const titlePos = findMarkerPosition(content, MARKER_TITLE);
+ const tocPos = findMarkerPosition(content, MARKER_TOC);
+ const contentPos = findMarkerPosition(content, MARKER_CONTENT);
+
+ let h1Content = '';
+ let documentContent = '';
+
+ if (titlePos !== -1 && contentPos !== -1) {
+ // File has markers - extract existing content
+ // Extract H1 between title marker and either TOC marker or content marker
+ const h1Start = titlePos + MARKER_TITLE.length;
+ const h1End = tocPos !== -1 ? tocPos : contentPos;
+ h1Content = content.substring(h1Start, h1End).trim();
+
+ // Extract document content after content marker
+ documentContent = content
+ .substring(contentPos + MARKER_CONTENT.length)
+ .trim();
+ } else {
+ // Plain Markdown file without markers - extract H1 and content
+ const h1Match = content.match(/^#\s+(.+)$/m);
+ if (h1Match) {
+ h1Content = h1Match[0];
+ // Extract everything after the H1
+ const h1Index = content.indexOf(h1Content);
+ documentContent = content
+ .substring(h1Index + h1Content.length)
+ .trim();
+ } else {
+ console.warn(
+ `⚠️ No H1 found in ${filePath}, using display name`
+ );
+ h1Content = `# ${fileMeta.displayName}`;
+ documentContent = content;
+ }
+ }
+
+ // Generate breadcrumb and TOC
+ const breadcrumb = generateBreadcrumb(filePath, metadata);
+ const toc = generateTOC(filePath, metadata);
+
+ // Ensure we have an H1
+ if (!h1Content) {
+ h1Content = `# ${fileMeta.displayName}`;
+ }
+
+ // Build new content with structure:
+ // Breadcrumb marker → breadcrumb → Title marker → H1 → TOC marker → TOC → Content marker → rest
+ let newContent = '';
+
+ // Breadcrumb section (only if there's a breadcrumb)
+ if (breadcrumb) {
+ newContent += MARKER_BREADCRUMBS + '\n';
+ newContent += '\n' + breadcrumb + '\n';
+ newContent += '\n'; // Blank line before title marker
+ }
+
+ // Title section
+ newContent += MARKER_TITLE + '\n\n';
+ newContent += h1Content + '\n';
+
+ // TOC section (only if there's a TOC)
+ if (toc) {
+ newContent += '\n' + MARKER_TOC + '\n\n';
+ newContent += toc + '\n\n';
+ } else {
+ // No TOC, but still need blank line before content marker
+ newContent += '\n';
+ }
+
+ // Document content
+ newContent += MARKER_CONTENT;
+ if (documentContent) {
+ newContent += '\n\n' + documentContent;
+ }
+
+ // Ensure trailing newline at end of file
+ if (!newContent.endsWith('\n')) {
+ newContent += '\n';
+ }
+
+ // Verify the new content is different before writing
+ if (newContent === content) {
+ // Content unchanged, skip write
+ return true;
+ }
+
+ // Delete old file and write new content to ensure clean slate
+ // This prevents any potential caching or partial write issues
+ fs.unlinkSync(fullPath);
+ fs.writeFileSync(fullPath, newContent, 'utf-8');
+
+ // Verify the write succeeded by reading back
+ const verification = fs.readFileSync(fullPath, 'utf-8');
+ if (verification !== newContent) {
+ console.error(
+ `❌ Verification failed for ${filePath}: Content mismatch after write`
+ );
+ return false;
+ }
+
+ return true;
+ } catch (err) {
+ console.error(`❌ Error updating ${filePath}:`, err.message);
+ return false;
+ }
+}
+
+// ============================================================================
+// MAIN
+// ============================================================================
+
+function main() {
+ const docsRoot = process.argv[2] || '../../';
+ const docsPath = path.resolve(__dirname, docsRoot);
+
+ console.log('📚 Regenerating CONTRIBUTOR-DOCS navigation...\n');
+ console.log(` Root: ${docsPath}\n`);
+
+ // Step 1: Extract metadata
+ console.log('🔍 Extracting metadata...');
+ const startTime = Date.now();
+ const metadata = walkTree(docsPath);
+ const extractTime = Date.now() - startTime;
+ console.log(
+ ` ✓ Found ${Object.keys(metadata.files).length} files and ${Object.keys(metadata.folders).length} folders (${extractTime}ms)\n`
+ );
+
+ // Step 2: Update all files
+ console.log('📝 Updating files...');
+ let updateCount = 0;
+ let skipCount = 0;
+
+ for (const filePath of Object.keys(metadata.files)) {
+ if (updateFile(filePath, metadata, docsPath)) {
+ updateCount++;
+ console.log(` ✓ ${filePath}`);
+ } else {
+ skipCount++;
+ }
+ }
+
+ const totalTime = Date.now() - startTime;
+
+ console.log(`\n✅ Complete!`);
+ console.log(` Updated: ${updateCount} files`);
+ if (skipCount > 0) {
+ console.log(` Skipped: ${skipCount} files`);
+ }
+ console.log(` Total time: ${totalTime}ms\n`);
+}
+
+// Run if called directly
+main();
+
+export { walkTree, generateBreadcrumb, generateTOC, updateFile };
diff --git a/CONTRIBUTOR-DOCS/03_style-guide/README.md b/CONTRIBUTOR-DOCS/03_style-guide/README.md
new file mode 100644
index 00000000000..7473254d849
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/03_style-guide/README.md
@@ -0,0 +1,11 @@
+
+
+[CONTRIBUTOR-DOCS](../README.md) / Style Guide
+
+
+
+# Style Guide
+
+
+
+(Content to be added)
diff --git a/CONTRIBUTOR-DOCS/04_workstream-info/01_2nd-gen-definition-and-development/README.md b/CONTRIBUTOR-DOCS/04_workstream-info/01_2nd-gen-definition-and-development/README.md
new file mode 100644
index 00000000000..235447ceaed
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/04_workstream-info/01_2nd-gen-definition-and-development/README.md
@@ -0,0 +1,18 @@
+
+
+[CONTRIBUTOR-DOCS](../../README.md) / [Workstream Info](../README.md) / 2nd-gen Definition and Development
+
+
+
+# 2nd-gen Definition and Development
+
+
+
+Building the 2nd-gen project from the ground up as a clean foundation for future work. This workstream encompasses multiple parallel efforts:
+
+- Developing the rendering layer and component architecture
+- Implementing tooling, infrastructure, and build improvements
+- Setting up tests, Storybook, and documentation
+- Improving code quality and developer experience
+
+Most work toward Unification, building a clean foundation for future work, and landing full-fidelity Spectrum 2 flows into this workstream.
diff --git a/CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/01_status.md b/CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/01_status.md
new file mode 100644
index 00000000000..721870cf6fa
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/01_status.md
@@ -0,0 +1,80 @@
+
+
+[CONTRIBUTOR-DOCS](../../README.md) / [Workstream Info](../README.md) / [2nd-gen Component Migration](README.md) / Status
+
+
+
+# Status
+
+
+
+| Component | [Factor Component](02_step-by-step/01_factor-rendering-out-of-1st-gen-component.md) | [Move to Core](02_step-by-step/02_move-base-class-to-2nd-gen-core.md) | [Add Data Model](02_step-by-step/03_formalize-spectrum-data-model.md) | [Add 2nd-Gen](02_step-by-step/04_implement-2nd-gen-component.md) | [Render & Style](02_step-by-step/05_migrate-rendering-and-styles.md) | [Add Stories](02_step-by-step/06_add-stories-for-2nd-gen-component.md) |
+| ------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| Accordion | | | | | | |
+| Action Bar | | | | | | |
+| Action Button | | | | | | |
+| Action Group | | | | | | |
+| Action Menu | | | | | | |
+| Alert Banner | ✓ | | | | | |
+| Alert Dialog | | | | | | |
+| Asset | ✓ | | | | | |
+| Avatar | | | | | | |
+| Badge | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Breadcrumbs | | | | | | |
+| Button | | | | | | |
+| Button Group | | | | | | |
+| Card | | | | | | |
+| Checkbox | | | | | | |
+| Clear Button | | | | | | |
+| Close Button | | | | | | |
+| Coachmark | | | | | | |
+| Color Area | | | | | | |
+| Color Field | | | | | | |
+| Color Handle | | | | | | |
+| Color Loupe | | | | | | |
+| Color Slider | | | | | | |
+| Color Wheel | | | | | | |
+| Combobox | | | | | | |
+| Contextual Help | | | | | | |
+| Dialog | | | | | | |
+| Divider | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Dropzone | | | | | | |
+| Field Group | | | | | | |
+| Field Label | | | | | | |
+| Help Text | | | | | | |
+| Icon | | | | | | |
+| Icons | | | | | | |
+| Icons UI | | | | | | |
+| Icons Workflow | | | | | | |
+| Iconset | | | | | | |
+| Illustrated Message | | | | | | |
+| Infield Button | | | | | | |
+| Link | | | | | | |
+| Menu | | | | | | |
+| Meter | | | | | | |
+| Modal | | | | | | |
+| Number Field | | | | | | |
+| Overlay | | | | | | |
+| Picker | | | | | | |
+| Picker Button | | | | | | |
+| Popover | | | | | | |
+| Progress Bar | | | | | | |
+| Progress Circle | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Radio | | | | | | |
+| Search | | | | | | |
+| Sidenav | | | | | | |
+| Slider | | | | | | |
+| Split View | | | | | | |
+| Status Light | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Swatch | | | | | | |
+| Switch | | | | | | |
+| Table | | | | | | |
+| Tabs | | | | | | |
+| Tags | | | | | | |
+| Textfield | | | | | | |
+| Thumbnail | | | | | | |
+| Toast | | | | | | |
+| Tooltip | | | | | | |
+| Top Nav | | | | | | |
+| Tray | | | | | | |
+| Underlay | | | | | | |
diff --git a/CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/02_step-by-step/01_factor-rendering-out-of-1st-gen-component.md b/CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/02_step-by-step/01_factor-rendering-out-of-1st-gen-component.md
new file mode 100644
index 00000000000..61aa3615978
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/02_step-by-step/01_factor-rendering-out-of-1st-gen-component.md
@@ -0,0 +1,18 @@
+
+
+[CONTRIBUTOR-DOCS](../../../README.md) / [Workstream Info](../../README.md) / [2nd-gen Component Migration](../README.md) / Step By Step / Factor rendering out of 1st-gen component
+
+
+
+# Factor rendering out of 1st-gen component
+
+
+
+- Use `git mv` to rename `[Component].ts` to `[Component].base.ts`
+- Create a new `[Component].ts` file
+- In `[Component].base.ts`, edit the component definition to make it an abstract class named `[Component]Base`
+- In `[Component].ts`, import the `[Component]Base` class and define a new `[Component]` class extending from `[Component]Base`
+- Move the stylesheet import from the `[Component].base.ts` file to the `[Component].ts` file
+- Move the `render()` method and the static `styles` getter from the `[Component]Base` class to the `[Component]` class
+- If the 1st-gen component has any rendering code that has been factored out of the `render()` method (e.g., into helper methods), move that code from `[Component]Base` to `[Component]` as well
+- Confirm that the refactored component still renders and behaves the same, and that all tests continue to pass
diff --git a/CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/02_step-by-step/02_move-base-class-to-2nd-gen-core.md b/CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/02_step-by-step/02_move-base-class-to-2nd-gen-core.md
new file mode 100644
index 00000000000..8f4ff189bba
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/02_step-by-step/02_move-base-class-to-2nd-gen-core.md
@@ -0,0 +1,16 @@
+
+
+[CONTRIBUTOR-DOCS](../../../README.md) / [Workstream Info](../../README.md) / [2nd-gen Component Migration](../README.md) / Step By Step / Move base class to 2nd-gen core
+
+
+
+# Move base class to 2nd-gen core
+
+
+
+- Create a directory for the component under `core/components`
+- Move `[Component].base.ts` file from 1st-gen
+- Add `index.ts` file
+- Add the 2nd-gen `core` library to `dependencies` in the 1st-gen component's `package.json` file
+- Update import statements in `[Component].ts` to import `[Component]Base.ts` from 2nd-gen `core`
+- Confirm that the 1st-gen component still renders and behaves the same, and that all tests continue to pass
diff --git a/CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/02_step-by-step/03_formalize-spectrum-data-model.md b/CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/02_step-by-step/03_formalize-spectrum-data-model.md
new file mode 100644
index 00000000000..7ebc7c797cf
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/02_step-by-step/03_formalize-spectrum-data-model.md
@@ -0,0 +1,23 @@
+
+
+[CONTRIBUTOR-DOCS](../../../README.md) / [Workstream Info](../../README.md) / [2nd-gen Component Migration](../README.md) / Step By Step / Formalize Spectrum data model
+
+
+
+# Formalize Spectrum data model
+
+
+
+- Create a `[Component].types.ts` file in the `core/components/[component]` directory
+- Define shared constants (e.g., semantic variants, size values)
+- Define S1-specific constants and type unions
+- Define S2-specific constants and type unions
+- Define the union type that combines S1 and S2 values
+- Export all types and constants from the types file
+- Update the base class to:
+ - Import the union types
+ - Create section headers for API TO OVERRIDE, SHARED API, and IMPLEMENTATION
+ - Declare abstract static properties for generation-specific arrays (e.g., `VARIANTS_COLOR`, `STATIC_COLORS`)
+ - Declare properties with union types that need narrowing in concrete implementations
+ - Move shared static properties and standard API properties to SHARED API section
+ - Move helper methods and lifecycle methods to IMPLEMENTATION section
diff --git a/CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/02_step-by-step/04_implement-2nd-gen-component.md b/CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/02_step-by-step/04_implement-2nd-gen-component.md
new file mode 100644
index 00000000000..f6f06aa084c
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/02_step-by-step/04_implement-2nd-gen-component.md
@@ -0,0 +1,20 @@
+
+
+[CONTRIBUTOR-DOCS](../../../README.md) / [Workstream Info](../../README.md) / [2nd-gen Component Migration](../README.md) / Step By Step / Add 2nd-gen SWC component
+
+
+
+# Add 2nd-gen SWC component
+
+
+
+- Create directory structure: `second-gen/packages/swc/components/[component]/`
+- Create `[Component].ts` file extending from `[Component]Base`
+- Import S2-specific types and constants from `[Component].types.ts`
+- Add section headers: API OVERRIDES, API ADDITIONS (if needed), RENDERING & STYLING
+- In API OVERRIDES section:
+ - Override abstract static properties with S2-specific values
+ - Override properties that need type narrowing with S2-specific types
+- In API ADDITIONS section (if applicable):
+ - Add any S2-only properties (e.g., `subtle`, `outline` for Badge)
+- Re-export any S2-specific types and constants as needed for backward compatibility, marking them as deprecated
diff --git a/CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/02_step-by-step/05_migrate-rendering-and-styles.md b/CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/02_step-by-step/05_migrate-rendering-and-styles.md
new file mode 100644
index 00000000000..162f2116c7f
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/02_step-by-step/05_migrate-rendering-and-styles.md
@@ -0,0 +1,139 @@
+
+
+[CONTRIBUTOR-DOCS](../../../README.md) / [Workstream Info](../../README.md) / [2nd-gen Component Migration](../README.md) / Step By Step / Migrate rendering & styles from Spectrum CSS
+
+
+
+# Migrate rendering & styles from Spectrum CSS
+
+
+
+
+In this doc
+
+- [[TODO: Integrate this content]](#-todo-integrate-this-content-)
+- [Bring over styles from Spectrum CSS](#bring-over-styles-from-spectrum-css)
+- [Update styles in the 2nd-generation component](#update-styles-in-the-2nd-generation-component)
+
+
+
+
+
+## [ TODO: Integrate this content ]
+
+The following bits from the top-level migration guide outline need to be integrated into this doc:
+
+> - In RENDERING & STYLING section:
+> - Add static `styles` getter returning the S2 stylesheet
+> - Implement the `render()` method with S2 rendering logic
+> - Create the S2 stylesheet (`[component].css`)
+
+## Bring over styles from Spectrum CSS
+
+Now we can bring over styles from the `spectrum-two` package in Spectrum CSS. Start by checking out the `@adobe/spectrum-css` repository and pulling down the `spectrum-two` branch.
+
+Identify the component you need to migrate by searching the `components` directory for the component name.
+
+Inside the CSS directory, you can expect to find the following files:
+
+- `index.css` - This is the source of truth for the component Styles
+- `dist/index.css` - This is the processed version of the component styles; for now, this is the best place to source styles for SWC. When copying files from Spectrum CSS into the 2nd-generation component, using this file will ensure you get the benefits of the CSS build tooling.
+- `stories/.stories.js` - This is a great source-of-truth for the SWC storybook. These stories are organized into logic groups with API defined in a customer-friendly fashion with typing and human-readable labels. These files also include migration notes and guidance specific to the S2-specific implementation of the component.
+- `stories/template.js` - This is a great source-of-truth for the SWC render function; these templates already include property and class mappings. When bringing this file over to SWC, be sure to remove the `id` and `customStyles` attributes as they do not translate to the web component APIs.
+
+Next, we need to copy the styles from the Spectrum CSS component to the 2nd-generation component.
+
+```bash
+cp -r spectrum-css/components//dist/index.css spectrum-web-components/second-gen/packages/swc/components//.css
+```
+
+## Update styles in the 2nd-generation component
+
+Now that we have the base styles in place, we need to check the first-gen implementation for any unique web component-specific styles that would not exist in the vanilla CSS implementation. This information will most likely be found in the `first-gen/packages/components//.css` file.
+
+For example, look for styles specific to slots, such as `::slotted([name="icon"]) {}`.
+
+If these styles are found, we need to confirm if they are needed in the 2nd-generation component. Not all first-gen overrides or component-specific styles are needed in the 2nd-generation components and sometimes there are other ways to source those styles using the original classes provided by the Spectrum CSS asset.
+
+It might be helpful, at this point, to define the render function for the second-gen component so you can spin up Storybook and start seeing these new styles in action. A quick way to kick this off is to copy the `spectrum-css/components//stories/template.js` file into a render function on your new 2nd-generation component.
+
+Let's use the `Badge` component as an example. First, we need to add the styles to the component.
+
+Start by importing the CSS file:
+
+```ts
+import styles from './badge.css';
+```
+
+Next, we import those styles into the component:
+
+```ts
+public static override get styles(): CSSResultArray {
+ return [styles];
+}
+```
+
+Finally, we can start to implement the render function:
+
+```ts
+protected override render(): TemplateResult {
+ return html`
+
+ `;
+}
+```
+
+As you can see, the 2nd-generation implementation leverages the `classMap` function to conditionally apply classes to the component based on the component's properties. This is a common pattern in the 2nd-generation components. This approach has several benefits:
+
+- It separates the styling application from the properties and states of the component
+- It creates a container inside the Shadow DOM which provides stronger encapsulation
+- It allows for more efficient rendering by only applying the necessary classes to the component
+
+In our 2nd-generation version, we will likely want to maintain any slots available in the 1st-generation component unless design changes from S2 provide a compelling reason to change or remove them.
diff --git a/CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/02_step-by-step/06_add-stories-for-2nd-gen-component.md b/CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/02_step-by-step/06_add-stories-for-2nd-gen-component.md
new file mode 100644
index 00000000000..569c6a0fe2f
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/02_step-by-step/06_add-stories-for-2nd-gen-component.md
@@ -0,0 +1,24 @@
+
+
+[CONTRIBUTOR-DOCS](../../../README.md) / [Workstream Info](../../README.md) / [2nd-gen Component Migration](../README.md) / Step By Step / Add stories for 2nd-gen component
+
+
+
+# Add stories for 2nd-gen component
+
+
+
+- Create `stories/[component].stories.ts` file
+- Add section headers: METADATA, STORIES, HELPER FUNCTIONS (if needed)
+- In METADATA section:
+ - Import `StoryObj as Story` for consistency
+ - Set up Storybook helpers with `getStorybookHelpers()`
+ - Configure argTypes for component-specific controls
+ - Define and export the meta object
+- In STORIES section:
+ - Create Default story (without `tags: ['!dev']`)
+ - Create additional stories showcasing variants, sizes, states
+ - Add `tags: ['!dev']` to all non-default stories
+- In HELPER FUNCTIONS section (if needed):
+ - Add any utility functions or template helpers
+ - Convert arrow functions to standard function declarations where appropriate
diff --git a/CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/README.md b/CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/README.md
new file mode 100644
index 00000000000..85df042d605
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/04_workstream-info/02_2nd-gen-component-migration/README.md
@@ -0,0 +1,34 @@
+
+
+[CONTRIBUTOR-DOCS](../../README.md) / [Workstream Info](../README.md) / 2nd-gen Component Migration
+
+
+
+# 2nd-gen Component Migration
+
+
+
+
+Beneath this doc
+
+- [Status](01_status.md)
+- Step By Step
+ - [Factor rendering out of 1st-gen component](02_step-by-step/01_factor-rendering-out-of-1st-gen-component.md)
+ - [Move base class to 2nd-gen core](02_step-by-step/02_move-base-class-to-2nd-gen-core.md)
+ - [Formalize Spectrum data model](02_step-by-step/03_formalize-spectrum-data-model.md)
+ - [Add 2nd-gen SWC component](02_step-by-step/04_implement-2nd-gen-component.md)
+ - [Migrate rendering & styles from Spectrum CSS](02_step-by-step/05_migrate-rendering-and-styles.md)
+ - [Add stories for 2nd-gen component](02_step-by-step/06_add-stories-for-2nd-gen-component.md)
+
+
+
+
+
+The tactical process of migrating individual components to the multi-generation architecture:
+
+- Refactoring 1st-gen components to separate core functionality from generation-specific rendering
+- Moving base classes into 2nd-gen Core
+- Building corresponding 2nd-gen implementations
+- Migrating styles from the Spectrum CSS repository
+
+Because our 1st-gen components vary in complexity and quality—some have known issues (a11y and otherwise) that we believe will require substantial changes or rewrites—we will add classes to 2nd-gen Core incrementally, based on component-specific roadmaps we'll build in parallel with spinning up the 2nd-gen project.
diff --git a/CONTRIBUTOR-DOCS/04_workstream-info/03_accessibility-improvements/README.md b/CONTRIBUTOR-DOCS/04_workstream-info/03_accessibility-improvements/README.md
new file mode 100644
index 00000000000..67323df3907
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/04_workstream-info/03_accessibility-improvements/README.md
@@ -0,0 +1,15 @@
+
+
+[CONTRIBUTOR-DOCS](../../README.md) / [Workstream Info](../README.md) / Accessibility Improvements
+
+
+
+# Accessibility Improvements
+
+
+
+Systematic work to maximize accessibility across all components:
+
+- Expanding documentation and examples
+- Conducting comprehensive accessibility audits
+- Addressing identified issues
diff --git a/CONTRIBUTOR-DOCS/04_workstream-info/04_component-improvements/README.md b/CONTRIBUTOR-DOCS/04_workstream-info/04_component-improvements/README.md
new file mode 100644
index 00000000000..cd03e6414ff
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/04_workstream-info/04_component-improvements/README.md
@@ -0,0 +1,16 @@
+
+
+[CONTRIBUTOR-DOCS](../../README.md) / [Workstream Info](../README.md) / Component Improvements
+
+
+
+# Component Improvements
+
+
+
+Ongoing enhancements to components:
+
+- Bug fixes
+- Feature additions
+- API clarity and consistency improvements
+- Major refactoring or replacement as needed
diff --git a/CONTRIBUTOR-DOCS/04_workstream-info/05_1st-gen-spectrum-2-enhancements/README.md b/CONTRIBUTOR-DOCS/04_workstream-info/05_1st-gen-spectrum-2-enhancements/README.md
new file mode 100644
index 00000000000..4f8dfdc70b0
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/04_workstream-info/05_1st-gen-spectrum-2-enhancements/README.md
@@ -0,0 +1,11 @@
+
+
+[CONTRIBUTOR-DOCS](../../README.md) / [Workstream Info](../README.md) / 1st-gen Spectrum 2 Enhancements
+
+
+
+# 1st-gen Spectrum 2 Enhancements
+
+
+
+Ongoing refinement of the `spectrum-two` theme in 1st-gen as needed to deliver production-quality Spectrum 2 support for customers using 1st-gen components.
diff --git a/CONTRIBUTOR-DOCS/04_workstream-info/README.md b/CONTRIBUTOR-DOCS/04_workstream-info/README.md
new file mode 100644
index 00000000000..cb64ed8f9be
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/04_workstream-info/README.md
@@ -0,0 +1,70 @@
+
+
+[CONTRIBUTOR-DOCS](../README.md) / Workstream Info
+
+
+
+# Workstream Info
+
+
+
+
+In this doc
+
+- [About Workstream Info](#about-workstream-info)
+- [Active Workstreams](#active-workstreams)
+- [Milestones](#milestones)
+ - [Barebones](#barebones)
+
+
+
+
+Beneath this doc
+
+- [2nd-gen Definition and Development](01_2nd-gen-definition-and-development/README.md)
+- [2nd-gen Component Migration](02_2nd-gen-component-migration/README.md)
+ - [Status](02_2nd-gen-component-migration/01_status.md)
+ - Step By Step
+- [Accessibility Improvements](03_accessibility-improvements/README.md)
+- [Component Improvements](04_component-improvements/README.md)
+- [1st-gen Spectrum 2 Enhancements](05_1st-gen-spectrum-2-enhancements/README.md)
+
+
+
+
+
+## About Workstream Info
+
+Workstreams represent our strategic objectives translated into actionable work. Each workstream defines a coherent body of work toward a specific goal, with its own scope, approach, and priorities.
+
+This section of the contributor docs contains detailed information about each of our active workstreams
+
+For more on how Workstream Info (this section) and [Component Info](../05_component-info/README.md) provide complementary views of our work, see the [main contributor docs README](../README.md#about-these-contributor-docs).
+
+## Active Workstreams
+
+- **[2nd-gen Definition and Development](./01_2nd-gen-definition-and-development/README.md)** - Building the 2nd-gen project from the ground up, including rendering layer, tooling, infrastructure, tests, Storybook, and documentation.
+
+- **[2nd-gen Component Migration](./02_2nd-gen-component-migration/README.md)** - Tactical process of migrating individual components to enable core functionality sharing between 1st-gen and 2nd-gen.
+
+- **[Accessibility Improvements](./03_accessibility-improvements/README.md)** - Systematic work to maximize accessibility through expanded documentation, comprehensive audits, and issue remediation.
+
+- **[Component Improvements](./04_component-improvements/README.md)** - Ongoing enhancements including bug fixes, feature additions, API improvements, and refactoring.
+
+- **[1st-gen Spectrum 2 Enhancements](./05_1st-gen-spectrum-2-enhancements/README.md)** - Ongoing refinement of the `spectrum-two` theme for 1st-gen customers.
+
+## Milestones
+
+### Barebones
+
+The Barebones milestone is the initial milestone in our 2nd-gen effort. Its purpose is to prove out and de-risk the strategy by establishing the multi-generation architecture with a small set of simple components.
+
+The work for this milestone is being done on the `barebones` branch and includes:
+
+- Moving virtually all previous repository contents into a new `first-gen/` folder
+- Creating the `second-gen/` folder structure with both the Core library and the 2nd-gen SWC library
+- Migrating 5 simple components to the new multi-generation architecture
+- Verifying that all existing 1st-gen tests still pass
+- Confirming that 1st-gen releases continue to work as expected
+
+The milestone will be considered complete when the `barebones` branch is merged into `main`, validating that the strategy is viable before scaling the approach to all components.
diff --git a/CONTRIBUTOR-DOCS/05_component-info/README.md b/CONTRIBUTOR-DOCS/05_component-info/README.md
new file mode 100644
index 00000000000..82ff21856fb
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/05_component-info/README.md
@@ -0,0 +1,21 @@
+
+
+[CONTRIBUTOR-DOCS](../README.md) / Component Info
+
+
+
+# Component Info
+
+
+
+
+Beneath this doc
+
+- Badge
+- Progress Circle
+
+
+
+
+
+(Content to be added)
diff --git a/CONTRIBUTOR-DOCS/README.md b/CONTRIBUTOR-DOCS/README.md
new file mode 100644
index 00000000000..976d9bc58c7
--- /dev/null
+++ b/CONTRIBUTOR-DOCS/README.md
@@ -0,0 +1,87 @@
+
+
+# Contributor Documentation
+
+
+
+
+In this doc
+
+- [About Spectrum Web Components](#about-spectrum-web-components)
+- [About the 1st-gen-to-2nd-gen transition](#about-the-1st-gen-to-2nd-gen-transition)
+- [About these docs](#about-these-docs)
+
+
+
+
+Beneath this doc
+
+- [Objectives and Strategy](01_objectives-and-strategy.md)
+- [Contributor Guides](02_contributor-guides/README.md)
+ - [Adobe Code of Conduct](02_contributor-guides/01_code-of-conduct.md)
+ - [Authoring contributor docs](02_contributor-guides/authoring-contributor-docs/README.md)
+- [Style Guide](03_style-guide/README.md)
+- [Workstream Info](04_workstream-info/README.md)
+ - [2nd-gen Definition and Development](04_workstream-info/01_2nd-gen-definition-and-development/README.md)
+ - [2nd-gen Component Migration](04_workstream-info/02_2nd-gen-component-migration/README.md)
+ - [Accessibility Improvements](04_workstream-info/03_accessibility-improvements/README.md)
+ - [Component Improvements](04_workstream-info/04_component-improvements/README.md)
+ - [1st-gen Spectrum 2 Enhancements](04_workstream-info/05_1st-gen-spectrum-2-enhancements/README.md)
+- [Component Info](05_component-info/README.md)
+ - Badge
+ - Progress Circle
+
+
+
+
+
+## About Spectrum Web Components
+
+Spectrum Web Components (SWC) is a library of web components that implements Adobe's Spectrum design system.
+
+While SWC is used primarily by Adobe product teams, it is open-sourced and available for general use.
+
+SWC is developed by a core team in Adobe Design Engineering, but we welcome contributions from inside and outside Adobe.
+
+## About the 1st-gen-to-2nd-gen transition
+
+Spectrum Web Components 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](./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:
+
+- **`first-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 `second-gen` workspace.
+
+ While we'll continue doing work in `first-gen` as needed to accomplish our goals, we expect this work to decrease steadily toward none.
+
+- **`second-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 `first-gen`, `second-gen`, or both. If you have any questions, please ask—we're happy to help.
+
+## About these docs
+
+These docs contain essential information about the SWC project for both maintainers (members of the core team) and contributors from outside the core team.
+
+The docs are organized into several sections to help you find the information you need:
+
+**[Objectives and Strategy](./01_objectives-and-strategy.md)** - Strategic context for the 1st-gen-to-2nd-gen transition, including our goals and approach. This explains why we're making this transition and how we're managing the work to advance multiple objectives in parallel while continuing to deliver value to customers.
+
+**[Contributor Guides](./02_contributor-guides/README.md)** - Topical guides for working on the project. This section includes guides for getting started, understanding processes, and accomplishing specific tasks like adding new components or editing these contributor docs themselves.
+
+**[Style Guide](./03_style-guide/README.md)** - Comprehensive style guide covering project-wide conventions and area-specific rules. This section is useful for human reference and for AI-assisted work, documenting our approaches to linting, JSDoc conventions, component structure, and other coding standards.
+
+**[Workstream Info](./04_workstream-info/README.md) and [Component Info](./05_component-info/README.md)** - These two sections contain detailed information about our work, for planning, execution and tracking purposes:
+
+- **Workstream Info** offers a workstream-centric view that focuses on cross-cutting work affecting many or all components. This docs in this section help us work toward specific objectives, understand how different types of work relate to each other, and coordinate efforts that span multiple components.
+
+- **Component Info** offers a component-centric view that focuses on individual components and how they're affected by multiple workstreams. The docs in this section are useful for understanding and managing a component's overall roadmap and status, taking into account the various workstreams that affect it.
+
+Together, these two views help us manage the project roadmap, ensuring we make progress on strategic objectives while maintaining clarity about the state and evolution of individual components.