Caseyisonit/docs audience reorg#6298
Draft
caseyisonit wants to merge 19 commits into
Draft
Conversation
…and content audit Adds two sibling strategy docs to project-planning/strategies/: - audience-based-docs-reorganization-plan.md — structural plan for reorganizing CONTRIBUTOR-DOCS and Storybook around audiences (for-consumers / for-contributors / for-maintainers / project-planning / reference). 12 phases, human-approval gate per phase. - audience-based-docs-content-audit.md — file-by-file destination map for all 143 contributor docs, plus 10 content observations (duplications, stub READMEs, scope overlaps, naming inconsistencies) tracked for follow-up content PRs. No implementation work in this commit — the plan and audit are the contract this branch is built around. Subsequent commits implement the plan one phase at a time, each gated on explicit human approval. The project-planning README's auto-generated TOC is regenerated to surface the new files. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Phase 2 of the audience-based docs reorganization plan
(CONTRIBUTOR-DOCS/project-planning/05_strategies/audience-based-docs-reorganization-plan.md).
Three sub-parts, committed together so the working tree is never left
with broken links:
2a. File moves (~143 renames). Every destination is locked in the
sibling content audit. Top-level structure becomes:
- for-consumers/ (using-the-issue-tracker.md — primary audience is bug
filers / feature requesters)
- for-contributors/ (most contributor content, style-guide/ nested
under it, authoring-contributor-docs/ holds the meta docs)
- for-maintainers/ (releasing-swc.md — only maintainer-only doc today)
- project-planning/ (unchanged content; numeric prefixes preserved
inside the subtree per audit observation 5)
Numeric prefixes (NN_) are stripped throughout for-contributors/,
for-consumers/, for-maintainers/. Several clarity renames per the audit:
- participating-in-pr-reviews.md → reviewing-pull-requests.md
- accessibility-testing.md → running-accessibility-tests.md
- using-stackblitz.md → maintaining-stackblitz-examples.md
- 13_writing-migration-guides.md → for-contributors/authoring-contributor-docs/
(it's a meta doc; belongs with the other authoring docs)
Required filename fixes:
- playwright-accessbility-testing.md (typo) → playwright-accessibility-testing.md
- visual-regresssion-testing.md (typo) → visual-regression-testing.md
- running-tests..md (double-dot) → running-tests.md
- pr_review-checklist.md (underscore) → pr-review-checklist.md
One content merge under strict no-edit rules (audit observation 4):
- 01_contributor-guides/11_2ndgen_testing.md was a 30-line stub that
duplicated content scope with style-guide/testing/testing-overview.md.
Both H2 sections ("Overview" + "Where to put tests") are copied
verbatim into testing-overview.md and placed between the existing
intro and the existing "What to test" section so the reading order
flows from framing → file locations → standards. Source file deleted.
No prose was rewritten; any latent contradictions are tracked for
follow-up content PRs per the audit.
2b. Intra-doc link rewrites + empty-dir cleanup. A depth-aware rewriter
resolves every relative markdown link against each moved file's OLD
path, looks the target up in the rename map, and writes a new relative
link from the file's NEW path to the target's NEW path. This handles
the style-guide subtree's depth shift (was 3 deep in CONTRIBUTOR-DOCS/,
now 4 deep under for-contributors/style-guide/, so outbound ../../../
paths needed an extra ..). Old empty directories left after `git mv`
are deleted so they don't pollute generated TOCs.
2c. Root CONTRIBUTOR-DOCS/README.md rewrite. The auto-generated TOC
("Beneath this doc") is regenerated against the new tree. The hand-
edited "About these docs" section is reframed around the four audience
folders (For consumers / For contributors / For maintainers / Project
planning) instead of the old topic groupings (Contributor Guides /
Style Guide / Project Planning).
One additional change carried in this commit by necessity: .husky/pre-commit
hardcoded the path to update-nav.js. The renamed location is now reflected
there so post-Phase-2 commits don't all fail the pre-commit hook. This is
the only supporting-file path-reference update in this commit; the rest
(.ai/, AGENTS.md, PULL_REQUEST_TEMPLATE.md, 2nd-gen/README.md, etc.) is
handled in Phase 3.
Verification gate: update-nav.js reports 844 links verified, all valid.
Out of scope for this commit (later phases of the plan):
- Path-reference updates in .ai/, AGENTS.md, PULL_REQUEST_TEMPLATE.md,
2nd-gen/README.md, and other supporting files that still point at the
old numeric paths. Phase 3 of the plan handles those.
- Storybook persona-first sidebar (Phase 4), SSOT generator (Phase 5),
consumer landing (Phase 6), customization cheatsheet (Phase 7),
component status matrix (Phase 8), when-to-use restructure (Phase 9).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
… (phase 3)
Phase 3 of the audience-based docs reorganization plan. Mechanical
pass: every file in the repo that referenced CONTRIBUTOR-DOCS/0X_*/
paths now points at the new audience-folder destinations from the
content audit. No content edits beyond path swaps and one breadcrumb-
line deletion (audit Observation 4 follow-up — Decision 2C).
Files updated (33):
.ai/ rules and skills (24 files):
- .ai/README.md
- 5 rules: stories-format.md, storybook-mdx-conversion.md,
contributor-doc-update.md, github-description.md, styles.md
- 12 SKILL.md files across migration-{prep,setup,api,a11y,styling,
testing,documentation,review}, accessibility-migration-analysis,
component-migration-analysis, consumer-migration-guide,
contributor-docs-nav
- 6 skill reference docs (migration-analysis-prompt.md,
consumer-migration-guide-prompt.md, ai-agent-instructions.md,
migration-plan-contract.md, tldr-component-css-guidelines.md,
migration-prep-template.md)
AGENTS and templates (3 files):
- 1st-gen/AGENTS.md, 2nd-gen/AGENTS.md
- .github/PULL_REQUEST_TEMPLATE.md
Inside CONTRIBUTOR-DOCS (5 files):
- Backtick-wrapped paths, GitHub URLs, and an ASCII folder-tree
diagram that Phase 2's markdown-link rewriter couldn't see:
- project-planning/03_components/avatar/migration-plan.md
- project-planning/02_workstreams/02_2nd-gen-component-migration/
02_step-by-step/01_washing-machine-workflow.md
- project-planning/02_workstreams/02_2nd-gen-component-migration/
02_step-by-step/01_analyze-rendering-and-styling/README.md
- for-contributors/running-accessibility-tests.md
- for-contributors/style-guide/typescript/component-types.md
(also: a vestigial migration breadcrumb from a prior reorg is
removed — Decision 2C)
Components dir (1 file, Decision 1A):
- 2nd-gen/packages/swc/components/tabs/migration.md — one-line link
from .../03_project-planning/03_components/tabs/migration-plan.md
to .../project-planning/03_components/tabs/migration-plan.md.
Consumer migration guide colocated with tabs; broken link forced
by Phase 2's renames. Pure path swap, no content change.
Out of scope for this commit:
- Storybook persona-first sidebar (Phase 4)
- SSOT generator wiring (Phase 5)
- Consumer landing page (Phase 6)
- Customization cheatsheet (Phase 7)
- Component status matrix (Phase 8)
- When-to-use restructure (Phase 9)
Plan and audit docs intentionally retain references to the OLD
numeric paths because they describe the FROM→TO change itself.
Verification gate: update-nav.js reports 844 links verified, all
valid.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…torybook residency audit
Refines the audience-based docs reorganization based on content-strategist
review. Key decisions:
1. Dual SSOT split by primary audience:
- GitHub-primary content (contributors, maintainers, planning) →
MD SSOTs in CONTRIBUTOR-DOCS/, auto-mirrored to Storybook
- Storybook-primary content (consumers, designers, evaluators,
reference) → MDX SSOTs in .storybook/docs/, NOT auto-mirrored
- reference/component-status moved to MDX SSOT so it can render
each component's status as a live <swc-badge>
2. Contribute subtree gated to dev builds entirely (was: only
project-planning was gated). Production Storybook ships only the
consumer-facing surface. Contributors are comfortable in code and
reach contributor docs via GitHub or local yarn dev.
3. .storybook/ reorganized: all docs under a single .storybook/docs/
parent. The current scattered top-level directories (learn-about-swc,
guides, contributor-docs, get-started) retire in favor of
.storybook/docs/{get-started,learn,reference,contribute}.
4. Customization section keeps all 5 existing long-form docs and ADDS
a new cheatsheet as the first page (was: cheatsheet was going to
replace the long-form docs).
New artifact:
- audience-based-docs-storybook-residency-audit.md — third sibling in
the planning trio. Codifies the residency principle, audits each of
the 17 hand-authored .storybook/ MDX files, locks the new
.storybook/docs/ layout, captures Observation 11 (latent consumer
content in focus-management.md).
Updates:
- audience-based-docs-reorganization-plan.md — Phases 4–11 rewritten;
Phase 5 (storybook directory reorganization) inserted; Phase 6
(selective + gated SSOT generator) inserted; Phase 7 (consumer
landing) moves SSOT to .storybook/docs/get-started/index.mdx with
live <swc-badge>; Phase 8 (customization cheatsheet) becomes
additive not replacement; Phase 9 (component status matrix) uses
MDX SSOT; Phase 11 (validate) gets dual dev + production smoke
tests; phases 12 + 13 renumbered.
- audience-based-docs-content-audit.md — Observation 11 added,
cross-link to the new residency audit.
- README TOCs regenerated to surface the new audit file.
Approval gate at the top of the plan still applies to implementation;
this commit only updates the planning artifacts.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Phase 4 of the audience-based docs reorganization. Reshapes Storybook's
sidebar at the config level — no directory moves yet (Phase 5 does the
physical reorganization).
Sidebar IA changes (main.ts):
- Learn about SWC titlePrefix → Learn
- Guides titlePrefix → Learn (customization + accessibility-guides fold
into the same persona section)
- Contributor docs titlePrefix → Contribute
- Core titlePrefix stays (Phase 9 establishes Reference properly when
the component status matrix lands)
- New Get started titlePrefix added; .storybook/get-started/ created
as an empty placeholder for Phase 7 content
- The entire Contribute block is wrapped in `storybookMode !== 'build'`
so production Storybook ships only the consumer-facing surface.
Contributors reach contributor docs via GitHub or local yarn dev.
storySort updates (preview.ts):
- Order: Get started → Components → Patterns → Learn → Core →
Contribute (was: Learn about SWC → Core → Components → Patterns →
Guides → Contributor docs)
- Customization sub-order adds Cheatsheet first; long-form docs follow
Outbound-link updates (11 links across 6 component-dir files):
- typography/stories/typography.stories.ts (1 link)
- status-light/stories/status-light.stories.ts (2 links)
- progress-circle/stories/progress-circle.stories.ts (1 link)
- badge/stories/badge.stories.ts (1 link)
- button/stories/button.stories.ts (4 links)
- button/consumer-migration-guide.mdx (2 links)
Three URL transformations applied:
- /docs/guides-customization-fonts--readme
→ /docs/learn-customization-fonts--readme
- /docs/guides-customization-global-element-styling--readme
→ /docs/learn-customization-global-elements--readme
(picks up Phase 5 filename hygiene: global-element-styling →
global-elements)
- /docs/guides-accessibility-guides-screen-reader-testing--readme
→ /docs/learn-accessibility-screen-reader-testing--readme
(picks up Phase 5 folder rename: accessibility-guides → accessibility)
These are the only components/ diffs in the audience reorg PR. Pure
mechanical link redirects, forced by the titlePrefix renames. No
prose, JSDoc, or story-shape changes.
Internal Storybook MDX cross-link updates (11 files in .storybook/):
- All /docs/guides-customization-* and /docs/guides-accessibility-guides-*
cross-links between sibling MDX files updated to the Phase 5 final
URLs. Includes special cases for the accessibility-resources doubled
prefix and semantic-html-aria → semantic-html-and-aria spelling fix.
Intermediate-state note: the outbound links and storybook cross-links
target URLs that Phase 5 will make resolvable (directory moves,
<Meta title> updates). Between Phase 4 and Phase 5 commits, some
in-Storybook routes won't resolve — by design. Phase 5 fixes this in
the same PR. Updating links once at final state minimizes total churn.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Phase 5 of the audience-based docs reorganization. Physically moves the
16 hand-authored MDX doc files from .storybook/learn-about-swc/ and
.storybook/guides/ into the new .storybook/docs/learn/ tree. Updates
main.ts directory paths, preview.ts storySort to match new Meta titles,
and rewrites stale .storybook/guides/ and .storybook/learn-about-swc/
path references that were sitting in CONTRIBUTOR-DOCS.
Moves (16 MDX + 8 image assets):
learn-about-swc/ → docs/learn/
overview.mdx → about-swc.mdx
(Meta: "Overview" → "About SWC")
first-gen-vs-second-gen.mdx → first-gen-vs-second-gen.mdx
(Meta: "Gen1 vs Gen2" → "1st-gen vs 2nd-gen")
when-to-use-swc.mdx → when-to-use-swc.mdx
(Meta unchanged)
guides/customization/ → docs/learn/customization/
All 5 long-form docs moved intact (cheatsheet added in Phase 8).
Only global-elements.mdx gets Meta title hygiene:
"Customization/Global Element Styling" → "Customization/Global elements"
guides/accessibility-guides/ → docs/learn/accessibility/
All 8 MDXes renamed (underscores → hyphens) and Meta titles
normalized ("Accessibility guides/X" → "Accessibility/X"):
accessibility_resources.mdx → resources.mdx
(Meta: "Accessibility guides/Accessibility resources"
→ "Accessibility/Resources")
accessible_pattern_libraries.mdx → accessible-pattern-libraries.mdx
headings_and_landmarks.mdx → headings-and-landmarks.mdx
keyboard_testing.mdx → keyboard-testing.mdx
screen_reader_testing.mdx → screen-reader-testing.mdx
semantic_html_aria.mdx → semantic-html-and-aria.mdx
wave_toolbar_testing.mdx → wave-toolbar-testing.mdx
overview.mdx (Meta normalized only)
8 image assets in assets/images/ moved alongside the MDXes
(preserves the ./assets/images/... relative imports).
Placeholders:
docs/get-started/.gitkeep — Phase 7 will add index.mdx
docs/reference/.gitkeep — Phase 9 will add component-status.mdx
main.ts:
- Old `directory: 'get-started'` → `'docs/get-started'`
- Two prior Learn entries (one for learn-about-swc, one for guides)
consolidate into a single `directory: 'docs/learn'` entry
preview.ts storySort: title strings updated to match new Meta titles
- Top of Learn: About SWC, 1st-gen vs 2nd-gen, When to use SWC
- Customization: Global elements (was Global Element Styling)
- Accessibility (was Accessibility guides): Overview, Semantic HTML
and ARIA, …, Resources (was Accessibility resources)
Old directories deleted (now empty):
.storybook/learn-about-swc/
.storybook/guides/customization/
.storybook/guides/accessibility-guides/
.storybook/guides/
Path-reference updates in supporting files (CONTRIBUTOR-DOCS + .ai/):
14 files updated. Stale references to .storybook/learn-about-swc/* or
.storybook/guides/* point at the new docs/learn/* locations. Same
shape as Phase 3's path-reference pass; this is the Storybook-side
counterpart forced by the directory moves.
Plan and audit docs intentionally retain their old-path mentions
(they describe the change itself).
The 11 outbound component-dir links updated in Phase 4 now resolve
at their final URLs:
/docs/learn-customization-fonts--readme
/docs/learn-customization-global-elements--readme
/docs/learn-accessibility-screen-reader-testing--readme
Verification gate: yarn generate:contributor-docs runs cleanly (143
.md sources → 143 generated MDX); update-nav.js reports 855 links
verified, all valid.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…d) (phase 6)
Phase 6 of the audience-based docs reorganization. Updates the
generator to honor the audience-aware SSOT split (direction B):
GitHub-primary content (contributors, maintainers, planning) is
auto-mirrored to Storybook; consumer-primary content stays as
hand-authored MDX in .storybook/docs/.
generate-contributor-docs.mjs changes:
- New INCLUDED_AUDIENCE_FOLDERS constant gates the walker to
for-contributors/, for-maintainers/, project-planning/. Other
CONTRIBUTOR-DOCS subtrees (for-consumers/, reference/) are
intentionally NOT mirrored — consumer-primary content has its
MDX SSOTs in .storybook/docs/{get-started,learn,reference}/.
- Output target moved: .storybook/contributor-docs/ →
.storybook/docs/contribute/.
- Doc-ID prefix changed: contributor-docs-* → contribute-*. Routes
become /docs/contribute-for-contributors-*, /docs/contribute-
for-maintainers-*, /docs/contribute-project-planning-*.
- Sort-order assembly walks the included folders explicitly rather
than the CONTRIBUTOR-DOCS root, so the regenerated section drops
the prior 'Contributor documentation' root entry and the
'For consumers' subtree that no longer exists in the output.
main.ts:
- Contribute titlePrefix entry now points at directory:
'docs/contribute' (was 'contributor-docs'). Still wrapped in
`storybookMode !== 'build'` gate from Phase 4.
.gitignore:
- .storybook/contributor-docs/ → .storybook/docs/contribute/
.ai/rules/storybook-mdx-conversion.md (rewrite):
- Documents the audience-aware SSOT model
- Lists which CONTRIBUTOR-DOCS folders are auto-mirrored and which
Storybook content is hand-authored MDX
- States the dev-only Contribute gate as a locked architectural
decision
- Codifies "do not edit auto-generated content" and "do edit
hand-authored content" rules
The old .storybook/contributor-docs/ generated tree is deleted.
Verification gate: yarn generate:contributor-docs emits 141 .mdx
files (39 for-contributors + 1 for-maintainers + 101 project-planning).
update-nav.js reports 855 links verified, all valid.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…mo (phase 7) Phase 7 of the audience-based docs reorganization. Creates the consumer welcome surface — the canonical entry point for app developers using SWC. Hand-authored MDX SSOT: - 2nd-gen/packages/swc/.storybook/docs/get-started/index.mdx Consumer welcome page with live <swc-badge variant="positive">Approved</swc-badge> inline demo. Sections: Welcome → Install → Your first component → Framework note → Where to go next. Under one screen of reading. Renders at /docs/get-started-welcome--readme. Cross-surface pointer (no content duplication): - 2nd-gen/README.md rewritten to point at the published Storybook URLs for full consumer onboarding, with a minimal install snippet for readers who never leave GitHub. Includes a separate brief section for contributors pointing at CONTRIBUTOR-DOCS. New authoring template: - CONTRIBUTOR-DOCS/for-contributors/authoring-contributor-docs/templates/consumer-quickstart.md Codifies required sections, frontmatter, heading rules, and voice guidance for future consumer quickstart pages. Notes that consumer quickstart pages are MDX SSOTs in .storybook/docs/, not Markdown in CONTRIBUTOR-DOCS. Audience landing: - CONTRIBUTOR-DOCS/for-consumers/README.md Explains the residency principle (consumer content lives in Storybook). Lists the one MD file in the folder (using-the-issue- tracker.md) and provides a URL table pointing at the consumer Storybook surfaces. Generator + nav side effects (auto-regenerated): - preview.ts storySort: adds Templates / Consumer quickstart entry under Authoring contributor docs. - 4 existing READMEs/index files have TOCs regenerated to reflect the new for-consumers/README.md and the new template file. The generator correctly EXCLUDES for-consumers/README.md from the Storybook mirror (consumer content stays in .storybook/docs/, per the residency principle codified in storybook-mdx-conversion.md). Verification gate: update-nav.js reports 859 links verified, all valid. yarn generate:contributor-docs emits 142 .mdx files. Note: the published Storybook URL format used in 2nd-gen/README.md (opensource.adobe.com/spectrum-web-components/docs/...) matches the homepage field in package.json. If 2nd-gen publishes elsewhere, the URLs may need follow-up correction in the validate phase. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…hase 8) Phase 8 of the audience-based docs reorganization. Adds two quick-reference companion pages to the Learn section. New hand-authored MDX SSOTs: - .storybook/docs/learn/customization/cheat-sheet.mdx Six copy-paste-ready snippets (stylesheet, app background, dark theme, large scale, component override, global token), plus a quick-reference table mapping topics to the five long-form customization docs that follow. The cheat sheet is the first entry under Learn / Customization; the long-form docs are unchanged. - .storybook/docs/learn/accessibility/cheat-sheet.mdx Seven action snippets (native button, accessible name, landmarks + h1, keyboard-only test, VoiceOver smoke test, WAVE scan, CI a11y command), plus a quick-reference table mapping topics to the eight long-form accessibility docs. The cheat sheet is the first entry under Learn / Accessibility; the long-form docs are unchanged. Cross-references updated to point at the cheat sheets first: - get-started/index.mdx (consumer landing) — accessibility link now points at cheat sheet, matching the customization link pattern - 2nd-gen/README.md — same change to accessibility link target - CONTRIBUTOR-DOCS/for-consumers/README.md — adds separate rows for the accessibility cheat sheet and the long-form accessibility docs, mirroring the existing customization rows preview.ts storySort: 'Cheat sheet' added as first child of both Customization and Accessibility subsections. Style note: the project linter standardized the term to "cheat sheet" (two words) — file names became cheat-sheet.mdx, Meta titles "Cheat sheet", routes /docs/learn-*-cheat-sheet--readme. All cross-references match. Verification gate: update-nav.js reports 859 links verified, all valid. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Phase 9 of the audience-based docs reorganization. Adds the first page of the Reference section: a component status matrix that dogfoods the library — every status and parity cell is a real live <swc-badge>. New files: - CONTRIBUTOR-DOCS/reference/component-status.data.ts TypeScript data module with `defaults` and per-component `overrides` (parity, Figma, StackBlitz, notes). Type-safe schema guards against typos in parity values. PR-discussable as the plan specified. - 2nd-gen/packages/swc/.storybook/blocks/ComponentStatusMatrix.tsx React component that walks the CEM, looks up overrides, and renders a 7-column table. Status and parity cells use the ref-based <swc-badge> pattern from the existing StatusBadge block, so they're live custom elements rather than text. Variant mappings: preview → fuchsia, stable → positive, deprecated/unsupported → negative outline, internal → neutral outline; parity full → positive, partial → notice, none → negative outline. - 2nd-gen/packages/swc/.storybook/docs/reference/component-status.mdx MDX SSOT. Imports the matrix component, renders it, and follows with "How to read" and "How to update" guidance. Route: /docs/reference-component-status--readme. Modified: - .storybook/main.ts — adds a Reference titlePrefix entry for docs/reference/. Core keeps its own titlePrefix for now; folding Core under Reference is a follow-up that would change existing /docs/core-* routes. - .storybook/preview.ts — Reference (with Component status first) added to storySort above Core. - .storybook/blocks/index.ts — exports the new matrix component. Deleted: - .storybook/docs/reference/.gitkeep (replaced by real content). Plan deviation worth flagging: the plan called for the data file to be .yml. Vite does not import YAML natively in this project and adding a YAML loader plugin would be a separate vite-config change. .data.ts gives us the same git/PR review experience plus type safety, with no plugin dependency. If we'd rather YAML in follow-up, swapping back is a small change. Verification gate: update-nav.js reports 859 links verified, all valid. The CEM exposes 23 swc-* tagged components today, so the matrix renders 23 rows. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…ed convention Main renamed the per-component consumer migration guide files from `consumer-migration-guide.mdx` to `migration-guide.mdx`. Phase 9.5 swept the Meta title references in the skill, but missed the output-path references — the `globs:` frontmatter, the output-path bullet, the "canonical format reference" pointer to the badge guide, and the opening instruction in the prompt body still directed generation to the old filename. Update those four lines so the skill writes to `migration-guide.mdx` consistently. The skill itself keeps its `consumer-migration-guide` name and directory — that name still accurately describes what the skill does (creates consumer-facing migration guides). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Brings in three commits from main: - #6295 docs(typography): fix incorrect import path in migration guide - #6288 refactor(upload-artifact): remove redundant data-preview-only mechanism - #6267 docs(tabs): added consumer migration guide for swc-tabs Resolved one modify/delete conflict on `2nd-gen/packages/swc/components/tabs/migration.md` in favor of main's deletion. The branch's edit was an incidental route-prefix sweep during the earlier main merge; main intentionally retired the old `migration.md` and replaced it with the properly-shaped `tabs/migration-guide.mdx` following the rename convention. Both incoming migration guides verified clean: no stale `/docs/{guides,learn-about-swc,resources}-*` URLs and no lingering `consumer-migration-guide.mdx` references. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
Contributor
📚 Branch Preview Links🔍 First Generation Visual Regression Test ResultsWhen 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: If the changes are expected, update the |
Brings in eight commits from main: - #6291 docs(ai): align consumer-migration-guide skill and document swc-<tag>.ts pattern - #6292 fix(color-wheel): refresh layout cache before ring hit-test - #6284 ci(publish): skip pre-commit hooks on automated release commit - #6301 fix(test-a11y): stabilize 2nd-gen ARIA snapshot tests - #6297 docs(stories): add StackBlitz links to 2nd-gen component stories - #6296 fix(core): add missing illustrated-message export to package.json - #6293 docs(color-loupe): add interactive button trigger to parent-driven visibility story - #6223 style(conversation-ai): define WHCM, typography utils, CSS patterns Resolved three content conflicts in favor of main, all aligning with conventions main establishes: - `.ai/README.md`: dropped "testing changes" from the consumer-migration-guide skill description (main intentionally narrowed scope per #6291) - `.storybook/blocks/StatusBadge.tsx`: switched the badge registration import from a relative path to the `@adobe/spectrum-wc/components/badge/swc-badge.js` package path (matches the surrounding code pattern and exercises the export map) - `color-loupe/migration-guide.mdx`: adopted title case (`Color Loupe`) in the Meta title (main #6291 standardizes title case for proper-noun component names in `<Meta>` blocks) Notable plan-impact observation captured separately in `research.md`: #6291 duplicates our Phase 9.5 commit `d0762dcaee` (skill output path fix), and #6297 establishes story `meta.parameters.stackblitz.url` as the SSOT for StackBlitz URLs (relevant to the CEM-driven matrix Q1). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…ames + drop stale generator output Two post-merge cleanups: 1. Delete `2nd-gen/packages/swc/.storybook/contributor-docs/` (untracked, 144 files, 1.8 MB). Stale output from an earlier aborted generator run; the current generator emits to `.storybook/docs/contribute/` per the storybook-mdx-conversion rule. 2. Apply main's #6291 title-case convention for proper-noun component names to all four multi-word migration guides: - color-loupe: H1 → `# Color Loupe migration guide` (Meta already title case from the merge resolution) - illustrated-message: Meta + H1 → `Illustrated Message` - progress-circle: Meta + H1 → `Progress Circle` - status-light: Meta + H1 → `Status Light` Main only applied the new convention to color-loupe (the file it directly touched in #6291); extending the same treatment to the other three keeps Storybook's component sidebar uniform. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Scope-tightening change for the audience-reorg PR. The team is splitting the live component status matrix (Phase 9 of the original plan) onto its own branch (`caseyisonit/cem-component-matrix`) so the audience-reorg diff stays focused on structural IA changes. Surgical removal of the matrix introduction (originally landed in `c68d10fe93`): - Delete `2nd-gen/packages/swc/.storybook/blocks/ComponentStatusMatrix.tsx` - Delete `2nd-gen/packages/swc/.storybook/docs/reference/component-status.mdx` - Delete `CONTRIBUTOR-DOCS/reference/component-status.data.ts` (and its now-empty parent directory) - Drop the `ComponentStatusMatrix` export from `.storybook/blocks/index.ts` - Drop `'Component status'` from the Reference storySort order in `preview.ts` - Update the Reference titlePrefix comment in `main.ts` to note the matrix is deferred - Drop the `- Reference` line from `CONTRIBUTOR-DOCS/README.md` (no longer hosts content here; the data-file directory is gone) Preserved (these were Phase 9.5 changes that should stay): - `Reference` titlePrefix still registered in `main.ts` — still hosts `changelog.mdx` and `support-and-compatibility.mdx` after the Resources retirement - `'Reference'` block in the storySort, now scoped to those two pages Also extends the gitignore to cover branch-suffixed research artifacts (`**/research-*.md`), matching the pattern adopted on `caseyisonit/cem-component-matrix`. This prevents an accidentally-tracked `research-cem-matrix.md` when working across both branches. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Brings in five commits from main: - #6290 docs(close-button): a11y migration analysis - #6308 fix(color-loupe): fix timeout with color-loupe tests - #6282 chore: cleaning up storybook file naming and hierarchy - #6294 feat(tooltip): gen2 migration plan - #6302 feat(ai): add rules for migration plan and code conformance adherence Conflict resolutions: 1. `2nd-gen/packages/swc/.storybook/preview.ts` — content conflict from two simultaneous storySort edits: main renamed the Conversational AI `'README'` entry to `'Pattern overview'` (matching its own MDX rename), while our branch had renamed `'Guides'` to `'Learn'` for the persona-first IA. Combined both: `['Pattern overview', 'Prompt field', 'User message']` under the `'Learn'` sub-tree. 2. Path divergence — main authored new content at the old `CONTRIBUTOR-DOCS/03_project-planning/03_components/...` paths; our branch had renamed the parent folder to `CONTRIBUTOR-DOCS/project-planning/...`. Moved both incoming files (close-button accessibility-migration-analysis + tooltip migration-plan) into the audience-folder paths and cleaned up the now-empty `03_project-planning/` directory. Stale-path sweep on incoming files (links written against main's old IA): - Tooltip migration plan: 4 link patterns rewritten from `02_style-guide/01_css/<numeric>_*.md` to `for-contributors/style-guide/css/<flat>.md`. - Close-button a11y analysis: 3 `keyboard_testing.mdx` references rewritten from the retired `guides/accessibility-guides/keyboard_testing.mdx` path to the new `docs/learn/accessibility/keyboard-testing.mdx` path (renamed + relocated + underscore→hyphen). - Tabs migration plan: 5 references to the retired `tabs/migration.md` file (deleted by main's #6267) rewritten to `tabs/migration-guide.mdx` — both the one real markdown link and the four descriptive inline-code mentions. Nav validator drops from 21 → 10 broken links after the sweep. The remaining 10 are all pre-existing-in-main issues carried in unchanged: 9 occurrences of the `#aria-relationship-wiring` anchor in tooltip/migration-plan.md (the target is an H4 heading; the validator only indexes H1–H3), plus 1 external `spectrum-css/components/tooltip/index.css` reference. Both classes pre-existed in main's authoring of these files; out of scope for this merge. New AI rules from #6302 (`.ai/rules/consistency-pass.md` and `.ai/rules/migration-phase-awareness.md`) landed additively with no conflict; they don't affect the audience-reorg plan but inform future migration workflow. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…efresh verification doc
Two changes that together restore Gate 1 (CONTRIBUTOR-DOCS link integrity) to a clean ✅ All links valid! state across all 1032 links.
1. Fix the 10 broken links in `project-planning/03_components/tooltip/migration-plan.md`:
- Promote `#### ARIA relationship wiring` → `### ARIA relationship wiring`. The validator in `update-nav.js:106` only indexes H2/H3 (regex `/^(#{2,3})\s+(.+)$/gm`), so the H4 target was unreachable. Promoting it makes the 9 in-doc references resolve. The section is 25+ lines of substantive content referenced 9 times — H3 reflects its actual importance better than the original H4. It now sits as a sibling of `Accessibility semantics notes (2nd-gen)` under the H2 `2nd-gen API decisions`.
- Rewrite the external `spectrum-css/components/tooltip/index.css` reference from a relative path (`../../../../../spectrum-css/...`, which points outside the SWC repo) to its GitHub URL on the spectrum-two branch (`https://github.com/adobe/spectrum-css/blob/spectrum-two/components/tooltip/index.css`).
2. Refresh the verification gate in `05_strategies/audience-based-docs-reorganization-plan.md`:
- Gate 1 expectation reaffirmed: ✅ All links valid! Zero broken links is a hard precondition for Phase 12, regardless of which side of the merge a link came from.
- Gate 4 (production build) updated: `/docs/resources-*` routes must be ABSENT now (the Resources titlePrefix was retired in Phase 9.5); `/docs/patterns-*` added to the required-present list.
- Manual smoke test: dropped the `Reference → Component status` step (matrix extracted to follow-up branch `caseyisonit/cem-component-matrix`); rewrote the `Resources → Migrate from Gen1` step to point at the new `Learn → Migration` sub-tree.
- Scope check exception list expanded to acknowledge the four multi-word migration-guide.mdx title-case cleanups (`color-loupe`, `illustrated-message`, `progress-circle`, `status-light`) from merge-cleanup commit `9fbf08d838`, plus a note on the matrix's relocation to the follow-up branch.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Motivation and context
Related issue(s)
Screenshots (if appropriate)
Author's checklist
Reviewer's checklist
patch,minor, ormajorfeaturesManual review test cases
Descriptive Test Statement
Descriptive Test Statement
Device review
Accessibility testing checklist
Required: Complete each applicable item and document your testing steps (replace the placeholders with your component-specific instructions).
Keyboard (required — document steps below) — What to test for: Focus order is logical; Tab reaches the component and all interactive descendants; Enter/Space activate where appropriate; arrow keys work for tabs, menus, sliders, etc.; no focus traps; Escape dismisses when applicable; focus indicator is visible.
Screen reader (required — document steps below) — What to test for: Role and name are announced correctly; state changes (e.g. expanded, selected) are announced; labels and relationships are clear; no unnecessary or duplicate announcements.