adobe · caseyisonit · Apr 24, 2026 · Apr 24, 2026
@@ -192,7 +192,7 @@ Skills are used on-demand. When a task matches a skill’s purpose, the agent re
 
 - **purpose**: Create accessibility migration analysis docs for the "analyze accessibility" step of 2nd-gen component migration
 - **How to invoke**: Say "create accessibility analysis for [component]", "analyze accessibility for [component]", or "accessibility migration for [component]". Also invoked when you refer to the "analyze accessibility" step in the 2nd-gen component migration workstream.
-- Use when: On the analyze-accessibility step for one or more components; creating one markdown file per component at `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component-name]/accessibility-migration-analysis.md`
+- Use when: On the analyze-accessibility step for one or more components; creating one markdown file per component at `CONTRIBUTOR-DOCS/project-planning/03_components/[component-name]/accessibility-migration-analysis.md`
 - Applies to: `CONTRIBUTOR-DOCS/**/accessibility-migration-analysis.md`
 - Provides: Required section order, ARIA recommendations structure, Shadow DOM guidance, keyboard and focus conventions, testing table format, reference examples
 
@@ -221,8 +221,8 @@ Skills are used on-demand. When a task matches a skill’s purpose, the agent re
 
 - **purpose**: Create rendering-and-styling migration analysis docs for the “analyze rendering and styling” step of 2nd-gen component migration
 - **How to invoke**: Say “create migration analysis for [component]”, “analyze rendering and styling for [component]”, or “rendering and styling migration for [component]”. Also invoked when you refer to the “analyze rendering and styling” step in the 2nd-gen component migration workstream.
-- Use when: On the analyze-rendering-and-styling step for one or more components; creating one markdown file per component at `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md`
-- Provides: Workflow summary (specs from CSS + SWC, three-way DOM comparison, CSS⇒SWC mapping table, summary). Full instructions in `CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_analyze-rendering-and-styling/cursor_prompt.md`
+- Use when: On the analyze-rendering-and-styling step for one or more components; creating one markdown file per component at `CONTRIBUTOR-DOCS/project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md`
+- Provides: Workflow summary (specs from CSS + SWC, three-way DOM comparison, CSS⇒SWC mapping table, summary). Full instructions in `CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_analyze-rendering-and-styling/cursor_prompt.md`
 
 #### Consumer migration guide
 

@@ -25,7 +25,7 @@ alwaysApply: false
 
 1. **Run the nav script** from the contributor docs script folder (from project root):
    ```bash
-   cd CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs
+   cd CONTRIBUTOR-DOCS/for-contributors/authoring-contributor-docs
    node update-nav.js
    ```
 2. **Confirm** the script completes without errors.

@@ -227,7 +227,7 @@ Common additional labels include:
 <!---
     Manual accessibility testing is required because automated tools cannot catch all issues (e.g. focus order, screen reader announcements, keyboard flow).
     You must document your keyboard and screen reader testing steps below. Reviewers will use this checklist during review.
-    See: [Accessibility testing guide](https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/01_contributor-guides/09_accessibility-testing.md)
+    See: [Accessibility testing guide](https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/for-contributors/accessibility-testing.md)
 -->
 
 **Required:** Complete each applicable item and document your testing steps (replace the placeholders with your component-specific instructions).

@@ -25,7 +25,7 @@ yarn generate:contributor-docs
 It is wired into `yarn storybook` and `yarn storybook:build`, so a normal dev loop regenerates on every start. The script:
 
 - Walks `CONTRIBUTOR-DOCS/` and emits one `.mdx` per `.md` under `.storybook/contributor-docs/`
-- Emits mirrored copies for files configured in `MIRROR_EMITS` (currently: `00_get-started/for-consumers.md` → `.storybook/get-started/index.mdx` with title `Get started`)
+- Emits mirrored copies for files configured in `MIRROR_EMITS` (currently: `for-consumers/get-started.md` → `.storybook/get-started/index.mdx` with title `Get started`)
 - Strips the auto-generated breadcrumbs + TOC blocks (they belong on GitHub, not Storybook)
 - Rewrites `.md` links to Storybook `/docs/...` paths and source-file links to GitHub URLs
 - Sanitizes HTML for MDX (self-closes void elements, converts `<user@example.com>` to `mailto:` links)

@@ -4,7 +4,7 @@ globs: *.css
 alwaysApply: true
 ---
 
-1. Follow rules outlined in the `CONTRIBUTOR-DOCS/02_style-guide` style guide directory.
+1. Follow rules outlined in the `CONTRIBUTOR-DOCS/for-contributors/style-guide` style guide directory.
 2. Auto-fix results based on settings defined by the `../../stylelint.config.js` unless it requires rewriting more than 30% of the line. Changes that impact more than 30% of the original content should prompt for update.
 3. Copyrights should reflect the current year.
 4. Comments added should always use sentence, never title case.

@@ -29,18 +29,18 @@ You are an accessibility auditor, not a documenter. Your job is to verify what t
 ### Output
 
 - **One markdown file per component** at:
-  `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component-name]/accessibility-migration-analysis.md`
+  `CONTRIBUTOR-DOCS/project-planning/03_components/[component-name]/accessibility-migration-analysis.md`
 - **Pairing:** Link to `./rendering-and-styling-migration-analysis.md` from **Overview → Also read**
-- **Nav:** After adding the file or changing `##` / `###` headings, run `node update-nav.js` from `CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs`. Register the doc in `03_components/README.md` when introducing a new component folder.
+- **Nav:** After adding the file or changing `##` / `###` headings, run `node update-nav.js` from `CONTRIBUTOR-DOCS/for-contributors/authoring-contributor-docs`. Register the doc in `03_components/README.md` when introducing a new component folder.
 
 ### Reference examples (consistency)
 
 Use these existing docs when matching structure, headings, tables, and phrasing:
 
-- `CONTRIBUTOR-DOCS/03_project-planning/03_components/badge/accessibility-migration-analysis.md`
-- `CONTRIBUTOR-DOCS/03_project-planning/03_components/divider/accessibility-migration-analysis.md`
-- `CONTRIBUTOR-DOCS/03_project-planning/03_components/progress-circle/accessibility-migration-analysis.md`
-- `CONTRIBUTOR-DOCS/03_project-planning/03_components/status-light/accessibility-migration-analysis.md`
+- `CONTRIBUTOR-DOCS/project-planning/03_components/badge/accessibility-migration-analysis.md`
+- `CONTRIBUTOR-DOCS/project-planning/03_components/divider/accessibility-migration-analysis.md`
+- `CONTRIBUTOR-DOCS/project-planning/03_components/progress-circle/accessibility-migration-analysis.md`
+- `CONTRIBUTOR-DOCS/project-planning/03_components/status-light/accessibility-migration-analysis.md`
 
 ### Important
 

@@ -27,7 +27,7 @@ You are a code archaeologist. Read existing code without judgment — your job i
 ### Output
 
 - **One markdown file per component** at:
-  `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md`
+  `CONTRIBUTOR-DOCS/project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md`
 - **Structure**: Component specifications (CSS from spectrum-css `spectrum-two` metadata.json; SWC from spectrum-web-components `main` render/slots) → Comparison (DOM structure changes: SWC + CSS main + CSS spectrum-two; CSS⇒SWC mapping table) → Summary of changes → Resources
 
 ### Sources and branches

@@ -2,7 +2,7 @@
 
 # Spectrum Migration Documentation Prompt
 
-For the **[COMPONENT_NAME]** component(s), create comprehensive migration documentation in individual markdown files under CONTRIBUTOR-DOCS: one file per component in `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md`, following this exact structure:
+For the **[COMPONENT_NAME]** component(s), create comprehensive migration documentation in individual markdown files under CONTRIBUTOR-DOCS: one file per component in `CONTRIBUTOR-DOCS/project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md`, following this exact structure:
 
 **IMPORTANT**: All files must be created on the original spectrum-web-components branch where the session started.
 
@@ -23,8 +23,8 @@ For additional context on goals and common pitfalls, reference `migration-roadma
 
 - **One markdown file per component**
 - Use the component/package name from the spectrum-web-components repository:
-- File path format: `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md`
-- Example: `CONTRIBUTOR-DOCS/03_project-planning/03_components/alert-banner/rendering-and-styling-migration-analysis.md`, `.../dialog/rendering-and-styling-migration-analysis.md`
+- File path format: `CONTRIBUTOR-DOCS/project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md`
+- Example: `CONTRIBUTOR-DOCS/project-planning/03_components/alert-banner/rendering-and-styling-migration-analysis.md`, `.../dialog/rendering-and-styling-migration-analysis.md`
 
 ## Component Documentation Structure
 
@@ -350,7 +350,7 @@ Under this heading, add a placeholder section for resources with a bulleted list
 
 ## Output format notes
 
-- Create one markdown file per component at `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md` (use the component's kebab-case folder name from spectrum-web-components)
+- Create one markdown file per component at `CONTRIBUTOR-DOCS/project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md` (use the component's kebab-case folder name from spectrum-web-components)
 - The filename is always `rendering-and-styling-migration-analysis.md`; the folder name is the component name
 - Use proper markdown formatting with Level 1 heading for component name
 - Ensure all <details> elements are properly closed

@@ -41,7 +41,7 @@ Create per-component migration guidance for application developers upgrading app
 
 - Consumer migration guides live alongside the Spectrum 2 component source so the doc ships with the component code. Do **not** add them to `CONTRIBUTOR-DOCS/`.
 - **Do not link to project-planning / `CONTRIBUTOR-DOCS` docs** from the guide. Those are maintainer-facing; consumers don't need them. Link only to public consumer docs (e.g. the Spectrum 1 README on npm or the Spectrum 2 component Storybook page) when a link genuinely helps.
-- **Nav:** The guide lives in the component directory, so the `CONTRIBUTOR-DOCS` `update-nav.js` script does not manage it. Do not register it in `CONTRIBUTOR-DOCS/03_project-planning/03_components/README.md`, and do not include auto-generated breadcrumbs or TOC markers intended for that script.
+- **Nav:** The guide lives in the component directory, so the `CONTRIBUTOR-DOCS` `update-nav.js` script does not manage it. Do not register it in `CONTRIBUTOR-DOCS/project-planning/03_components/README.md`, and do not include auto-generated breadcrumbs or TOC markers intended for that script.
 - **MDX gotchas:** Keep bare tag names (`<sp-badge>`, `<swc-badge>`, etc.) wrapped in backticks in prose, and keep HTML/JS examples inside fenced code blocks. Avoid loose `{` / `}` outside code blocks; MDX parses them as JS expressions.
 
 ### Required source inputs

@@ -50,7 +50,7 @@ If a claim is not confirmed by source, omit it.
 When sources disagree, follow this order of authority:
 
 1. **The shipped Spectrum 2 source** (`2nd-gen/packages/swc/components/[component-name]/` and `2nd-gen/packages/core/components/[component-name]/`) — ground truth for what the component actually does.
-2. **The CSS style guide** (`CONTRIBUTOR-DOCS/02_style-guide/` and `.ai/rules/styles.md`) — recommendations here **outweigh** anything in a component's `rendering-and-styling-migration-analysis.md`. The analysis docs are early, component-specific planning artifacts; the style guide is the canonical, cross-component rule set and supersedes them when they conflict (for example on custom-property naming, prefixing, and public-vs-private boundaries).
+2. **The CSS style guide** (`CONTRIBUTOR-DOCS/for-contributors/style-guide/` and `.ai/rules/styles.md`) — recommendations here **outweigh** anything in a component's `rendering-and-styling-migration-analysis.md`. The analysis docs are early, component-specific planning artifacts; the style guide is the canonical, cross-component rule set and supersedes them when they conflict (for example on custom-property naming, prefixing, and public-vs-private boundaries).
 3. **`rendering-and-styling-migration-analysis.md`** and other maintainer-facing analysis docs — use only for context and rationale. If an analysis doc suggests a public API shape that the Spectrum 2 source or the CSS style guide contradicts, trust the source and the style guide, not the analysis.
 
 ## File and heading format

@@ -30,7 +30,7 @@ You are a documentation maintainer. Broken links and stale navigation are bugs,
 1. **When to run**: File/folder add/remove/rename/move; heading changes; folder structure changes; or user request.
 2. **How to run** (from project root):
    ```bash
-   cd CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs
+   cd CONTRIBUTOR-DOCS/for-contributors/authoring-contributor-docs
    node update-nav.js
    ```
 3. **After running**: Verify success, report results (files updated, link counts). Fix straightforward link errors automatically; ask the user when the fix is ambiguous (e.g. target file removed, multiple anchor matches).

@@ -54,7 +54,7 @@ Execute the script when:
 ### How to run
 
 ```bash
-cd CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs
+cd CONTRIBUTOR-DOCS/for-contributors/authoring-contributor-docs
 node update-nav.js
 ```
 
@@ -127,7 +127,7 @@ The script automatically verifies all internal markdown links after updating nav
 ```
 Script reports: "File not found: ../migration/overview.md"
 → Search metadata for files matching "migration" or "overview"
-→ Find: "03_project-planning/01_migration-status.md"
+→ Find: "project-planning/01_migration-status.md"
 → Update link with correct relative path
 → Report: "Fixed broken link: updated path to migration status doc"
 ```

@@ -3,9 +3,9 @@ name: migration-a11y
 description: Phase 5 of 1st-gen to 2nd-gen component migration. Use to implement WCAG-aligned semantics, ARIA, keyboard support, and focus management, and document accessibility behavior.
 ---
 
-# Migration a11y ([Phase 5](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md))
+# Migration a11y ([Phase 5](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/README.md))
 
-[Phase 5](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is to implement WCAG-aligned behavior — semantics, ARIA, keyboard support, and focus management — and verify it with assistive technology and automated tests.
+[Phase 5](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is to implement WCAG-aligned behavior — semantics, ARIA, keyboard support, and focus management — and verify it with assistive technology and automated tests.
 
 See also: [`accessibility-compliance`](../accessibility-compliance/SKILL.md) for general WCAG 2.2 patterns, ARIA reference, and testing tools.
 
@@ -35,4 +35,4 @@ You are an implementer working from evidence, not assumptions. Read the accessib
 
 ## Workflow
 
-Follow **[Phase 5: Accessibility](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-5-accessibility)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase.
+Follow **[Phase 5: Accessibility](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-5-accessibility)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase.
@@ -3,9 +3,9 @@ name: migration-api
 description: Phase 3 of 1st-gen to 2nd-gen component migration. Use to move properties, methods, and types from 1st-gen to 2nd-gen while maintaining a clear public API.
 ---
 
-# Migration API ([Phase 3](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md))
+# Migration API ([Phase 3](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/README.md))
 
-[Phase 3](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is to migrate properties, methods, and types from 1st-gen to 2nd-gen — keeping the public API clear, types in core, and internal helpers marked appropriately.
+[Phase 3](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/README.md) of the 1st-gen → 2nd-gen component migration. The goal is to migrate properties, methods, and types from 1st-gen to 2nd-gen — keeping the public API clear, types in core, and internal helpers marked appropriately.
 
 ## Mindset
 
@@ -33,4 +33,4 @@ You are defining a contract, not writing logic. Every property and type you plac
 
 ## Workflow
 
-Follow **[Phase 3: API Migration](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-3-api-migration)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase.
+Follow **[Phase 3: API Migration](../../../CONTRIBUTOR-DOCS/project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-3-api-migration)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase.