docs(ai): update authoring rules and add sentence-case heading validation

[rise-erpelding]

Description

The docs-authoring source of truth that the four content PRs conform to (4 files):

• .ai/rules/: stories-documentation.md, stories-format.md, text-formatting.md
• scripts/validate-docs-pages.js: adds Check 5, enforcing sentence-case ###/#### headings for component and internal genres (patterns/controllers deliberately out of scope, not yet audited)

Motivation and context

This is 1 of 5 PRs splitting the oversized rise-erpelding/docs-site-small-updates branch (112 files) into reviewable pieces, divided by documentation surface. The original single PR was too large for GitHub and human reviewers to handle. Landing the authoring rules and validation as their own PR lets reviewers agree on the standard once, rather than re-deriving it per directory.

The five PRs together reproduce the original change set exactly (18 + 48 + 20 + 22 + 4 = 112 files, disjoint).

⚠️ Merge order: merge this last

The new Check 5 is run by the .husky/pre-commit hook against all in-scope MDX. If this merges before the docs are sentence-cased, it will trip the pre-commit hook for every contributor. Merge after:

• docs(migration-guides): standardize and normalize component migration guides #6525 (migration guides, component genre)
• docs(components): standardize component reference docs, stories, and API JSDoc #6526 (component reference docs, component + internal genres)

#6527 and #6528 are not policed by Check 5, so their order does not matter here.

Consistency notes

Known scope gap recorded for follow-up: patterns and controllers are not yet audited for sentence-case headings.

Related issue(s)

• SWC-2379
• Part of the branch split. Sibling PRs: docs(migration-guides): standardize and normalize component migration guides #6525, docs(components): standardize component reference docs, stories, and API JSDoc #6526, docs(storybook): normalize site guides and Storybook navigation #6527, docs: normalize patterns, core/controller docs, and contributor/tool docs #6528

Screenshots (if appropriate)

N/A

---

Author's checklist

• I have read the CONTRIBUTING and PULL_REQUESTS documents.
• I have included updated documentation (updates the .ai/rules authoring docs).
• Accessibility Practices — N/A (tooling / authoring rules change).
• Automated tests — N/A (validation-script logic; no component runtime change).
• Changeset — N/A (no published-package behavior change).

---

Manual review test cases

• Code review of the validate-docs-pages.js Check 5 logic (extractSubHeadings / isSentenceCase, PROPER_NOUN_PHRASES allowlist).
• Review the .ai/rules guidance updates.
• Confirm yarn lint:docs-pages passes once the component and migration-guide PRs (docs(migration-guides): standardize and normalize component migration guides #6525, docs(components): standardize component reference docs, stories, and API JSDoc #6526) are on main.

Device review / Accessibility testing

N/A (tooling and authoring-rules change; no rendered component behavior)

[changeset-bot]

⚠️ No Changeset found

Latest commit: 4a32580

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

[github-actions]

📚 Branch Preview Links

• Storybook (Gen2, dev mode)
• Storybook (Gen2, prod mode)
• Documentation Site (Gen1)
• Storybook (Gen1)

🔍 Gen1 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:

• Spectrum | Light | Medium | LTR
• Spectrum | Dark | Large | RTL
• Express | Light | Medium | LTR
• Express | Dark | Large | RTL
• Spectrum-two | Light | Medium | LTR
• Spectrum-two | Dark | Large | RTL
• High Contrast Mode | Medium | LTR

Deployed to Azure Blob Storage: pr-6529

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.

[coveralls]

Coverage Report for CI Build 30038316205

Warning

No base build found for commit efa4581 on main.
Coverage changes can't be calculated without a base build.
If a base build is processing, this comment will update automatically when it completes.

Coverage: 96.243%

Details

• Patch coverage: No coverable lines changed in this PR.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

Requires a base build to compare against. How to fix this →

---

Coverage Stats

Relevant Lines:	39208
Covered Lines:	37935
Line Coverage:	96.75%
Relevant Branches:	6466
Covered Branches:	6023
Branch Coverage:	93.15%
Branches in Coverage %:	Yes
Coverage Strength:	460.8 hits per line

---

💛 - Coveralls

[rise-erpelding]

📦 1 of 5 PRs splitting the oversized docs-site-small-updates branch (112 files) by doc surface. Siblings: #6525 (migration guides), #6526 (component reference), #6527 (site guides), #6528 (patterns/core).

🚨 MERGE THIS LAST. This PR adds Check 5 to validate-docs-pages.js — enforcing sentence-case ###/#### headings for component + internal genres — and the .husky/pre-commit hook runs it repo-wide. If it lands before the docs are sentence-cased, it will trip the pre-commit hook for every contributor. Merge after:

• docs(migration-guides): standardize and normalize component migration guides #6525 (migration guides — component genre)
• docs(components): standardize component reference docs, stories, and API JSDoc #6526 (component reference — component + internal genres)

#6527 and #6528 are not policed by Check 5, so their order doesn't matter here.

📝 Known scope gap recorded for follow-up: patterns and controllers are not yet audited for sentence-case headings.

[rise-erpelding]

This PR needs to be merged last after the first 4 go in (#6525, #6526, #6527, #6528 ), as it's flagging capitalization issues that are likely resolved in previous PRs. I believe this is why the lint step is failing. We can update the branch after those are in and see if that helps it pass, or add changes if it finds any additional.

[nikkimk]

Thanks for taking this on. Left a question and a few suggestions.

[pfulton]

I agree with @nikkimk's suggestions here and only have one of my own regarding a comment that was left in the validate-docs-pages script.

Let's get clarification on the capitalization rules for component names and I think we're good to go here. Please DM me on Slack when you're ready for a re-review or approval.

[Rajdeepc]

This PR is not needed for beta release. can we do this as a follow up clean up?
cc @pfulton

[najikahalsema]

One nit, but looks good! Thank you for all of these additions :)

Feedback has been addressed and this now has the required amount of approvals after requested changes were made.