Skip to content

docs: MVP-β restructure CONTRIBUTOR-DOCS around audiences#6206

Open
caseyisonit wants to merge 2 commits intocaseyisonit/docs-rfc-scaffoldingfrom
caseyisonit/docs-mvp-beta-audience-restructure
Open

docs: MVP-β restructure CONTRIBUTOR-DOCS around audiences#6206
caseyisonit wants to merge 2 commits intocaseyisonit/docs-rfc-scaffoldingfrom
caseyisonit/docs-mvp-beta-audience-restructure

Conversation

@caseyisonit
Copy link
Copy Markdown
Contributor

@caseyisonit caseyisonit commented Apr 24, 2026

Summary

Restructures CONTRIBUTOR-DOCS/ around audiences — for-consumers/, for-contributors/, for-agents/, for-internals/, for-maintainers/ — replacing the numeric-prefix folders (01_contributor-guides/, 02_style-guide/, ...) that hard-coded order at the expense of discoverability. Every top-level entry now answers "who are you?" before "what is it?"

Stack position: 7 of 7 — base is #6205 (RFC scaffolding). This is the largest PR in the stack because it renames 132 files; the diff is near-pure move/rename with cross-ref patches.

Part of the docs-overhaul-v2 rollout. See RFC: CONTRIBUTOR-DOCS/rfcs/proposed/2026-04-22-docs-overhaul-v2.md.

What changed

  • 132 file moves across CONTRIBUTOR-DOCS/ into audience-keyed folders
  • 78 cross-reference patches (23 from files outside CONTRIBUTOR-DOCS/ + 55 intra-doc) so no incoming links break
  • Generator-script paths updated — update-nav.js and verify-links.js moved to for-contributors/authoring-contributor-docs/; the .husky/pre-commit hook was patched to the new path
  • verify-links.js skips /docs/ paths so stable Storybook links pass through
  • Verification: 340/340 internal links resolve, 128 MDX pages generated, all 7 migrated components still render

Motivation

Numeric prefixes (01_, 02_, 03_) baked sibling ordering into filenames and gave no persona signal. Audience-keyed folders map 1:1 to the four top-level Storybook sections from the persona-first sidebar (MVP-3) and set up the IA for Phase 3 of the broader plan.

Related

  • Addresses MVP-β in the approved docs-overhaul-v2 plan
  • Unblocks Phase 3 IA work that depends on the audience shape

Accessibility testing checklist

Docs-only change — renames + cross-ref patches, no behavioral changes.

  • Keyboard — no interactive component surface touched; Storybook navigation unchanged.
  • Screen reader — heading and link structure preserved; link destinations updated to resolve to the new paths.

🤖 Generated with Claude Code

@caseyisonit
docs: restructure CONTRIBUTOR-DOCS around audiences (MVP-β)
4783a9e 
Moves all 132 tracked CONTRIBUTOR-DOCS files into audience-based folders
(for-consumers, for-contributors, for-maintainers, for-internals,
for-agents, reference, project-planning, rfcs), dropping numeric prefixes
except inside project-planning (audited in MVP-η). All moves use git mv
to preserve rename history; individual file contents unchanged.

Cross-reference patches:
- 23 files outside CONTRIBUTOR-DOCS (.ai/, .github/, 2nd-gen/, 1st-gen/)
  updated to point at the new audience-based paths.
- 55 intra-doc files updated for cross-links under the new tree.
- Generator scripts updated: generate-contributor-docs.mjs MIRROR_EMITS,
  generate-component-matrix.mjs output path, main.ts titlePrefix glob.
- verify-links.js now skips /docs/ stable Storybook paths per
  .ai/rules/storybook-mdx-conversion.md.
- .husky/pre-commit calls update-nav.js at its new path.

Verification:
- update-nav.js: 340/340 links valid
- yarn generate:contributor-docs: 128 MDX files + 2 mirror pages
- yarn generate:component-matrix: 7 components emitted to reference/

RFC: CONTRIBUTOR-DOCS/rfcs/proposed/2026-04-22-docs-overhaul-v2.md
@caseyisonit caseyisonit requested a review from a team as a code owner April 24, 2026 18:58
@changeset-bot
Copy link
Copy Markdown

changeset-bot Bot commented Apr 24, 2026 •
edited
Loading

⚠️ No Changeset found

Latest commit: 712dd51

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@caseyisonit caseyisonit added Component:Documentation Issues or PRs involving changes to docs or docs website. Component prefix is for Jira integration. Status:Ready for review PR ready for review or re-review. 2nd gen These issues or PRs map to our 2nd generation work to modernizing infrastructure. labels Apr 24, 2026
caseyisonit
caseyisonit commented Apr 24, 2026
View reviewed changes
Comment thread CONTRIBUTOR-DOCS/02_style-guide/01_css/README.md Outdated
Copy link
Copy Markdown
Contributor Author

@caseyisonit caseyisonit Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

moved not deleted

caseyisonit
caseyisonit commented Apr 24, 2026
View reviewed changes
Comment thread CONTRIBUTOR-DOCS/02_style-guide/README.md Outdated
Copy link
Copy Markdown
Contributor Author

@caseyisonit caseyisonit Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

moved not deleted

caseyisonit
caseyisonit commented Apr 24, 2026
View reviewed changes
Comment thread CONTRIBUTOR-DOCS/01_contributor-guides/README.md Outdated
Copy link
Copy Markdown
Contributor Author

@caseyisonit caseyisonit Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

moved not deleted

@caseyisonit
Copy link
Copy Markdown
Contributor Author

caseyisonit commented Apr 24, 2026

LIke i mentioned in the announcement, dont be intimidated by this PR, its purely reorganizing files in to the new directories that are audience based. no edits were made to content, only links were updated to the new file paths/names. A lot of files are renamed to remove the 00_ order in the file name, order will be set in frontmatter in a later phase.

@caseyisonit @claude
docs: fix MDX parse error in docs-overhaul-v2 RFC
712dd51 
The generated .mdx for the docs-overhaul-v2 RFC failed to index in
Storybook because MDX treats a few plain-prose angle-bracket
constructs as JSX:

- Two bare URL autolinks <https://spectrum-web-components.adobe.com/>
  (MDX reads `<https` as a tag and rejects `/` before the local name)
- Two `<5K tokens` / `<1M tokens` comparisons (MDX rejects a digit as
  the start of a tag name)

Rewrite the URL autolinks as `[label](url)` and switch the comparisons
to plain English ("under 5K tokens"). No content-meaning change.

Verified by compiling every generated MDX (129 files) through
@mdx-js/mdx — 0 failures.

Fixes the failing "Build and Deploy Job" check in the Preview
Documentation workflow on PR #6205.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Apr 24, 2026

📚 Branch Preview Links

🔍 First Generation Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

Deployed to Azure Blob Storage: pr-6206

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

2nd gen These issues or PRs map to our 2nd generation work to modernizing infrastructure. Component:Documentation Issues or PRs involving changes to docs or docs website. Component prefix is for Jira integration. Status:Ready for review PR ready for review or re-review.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@caseyisonit