feat(docs): enhance maturity badges with icons and tests (#1318)

[pratik wayase (PratikWayase)]

Description

Enhances the existing maturity badge system with icon support, accessible tooltips, and robust YAML ingestion guardrails. The previously inline badge logic in PackageCards has been extracted into a reusable MaturityBadge component to ensure UI consistency across the site.

Key changes include:

• Icons & Enterprise Wording: Emojis (✅, 🔶, 🧪) are rendered alongside updated, professional glossary text (e.g., "Production-ready / GA") for better scannability.
• Accessibility (WCAG Compliant): Replaced the inaccessible title attribute with a CSS-only tooltip driven by :focus-within and :hover. The badge is now a focusable element associated with the tooltip via aria-describedby, ensuring keyboard and touch users can access definitions.
• Dead Click Zone Fix: Applied pointer-events: none to the badge wrapper so clicks pass through to the card's stretched link overlay. The badge also accepts an href prop to act as a valid navigation link matching the card's destination.
• Unknown State & Guardrails: Added an explicit 'Unknown' fallback state (❓ icon) for unrecognized YAML values instead of silently defaulting to Experimental. Includes a dev-only console.warn guardrail to catch manifest typos early.
• Reusability: Extracted into docs/docusaurus/src/components/MaturityBadge/index.tsx with a size prop (sm / md) for upcoming collection detail pages.

Related Issue(s)

Relates to #1318
Relates to #1317 (Dynamically generate Docusaurus collection pages from YAML manifests)

Note: This PR addresses the UI/UX, Accessibility, and CSS layout blockers for the maturity badges. The backend logic to dynamically generate Docusaurus collection detail pages from YAML manifests will be scoped into a separate PR to keep the commit history clean.

Type of Change

Select all that apply:

Code & Documentation:

• Bug fix (non-breaking change fixing an issue)
• New feature (non-breaking change adding functionality)
• Breaking change (fix or feature causing existing functionality to change)
• Documentation update

Infrastructure & Configuration:

• GitHub Actions workflow
• Linting configuration (markdown, PowerShell, etc.)
• Security configuration
• DevContainer configuration
• Dependency update

AI Artifacts:

• Reviewed contribution with hve-builder and addressed all actionable findings
• Copilot instructions (.github/instructions/*.instructions.md)
• Copilot prompt (.github/prompts/*.prompt.md)
• Copilot agent (.github/agents/*.agent.md)
• Copilot skill (.github/skills/*/SKILL.md)
• Copilot hook (.github/hooks/*/*.json)
• Eval spec added/updated for changed AI artifacts (evals/)

Testing

• Created a new Jest test suite at docs/docusaurus/src/components/MaturityBadge/__tests__/index.test.tsx.
• Tested the normalizeMaturity() function to verify lowercase YAML values map correctly to Title-case.
• Verified the 'Unknown' fallback state renders correctly for invalid/empty inputs and logs a dev warning.
• Used it.each to verify all maturity levels render correct icons, CSS classes, and accessible tooltip content.
• Included jest-axe accessibility testing to ensure no a11y violations.
• Ran npm run validate:docs locally to confirm all 95 tests and validation checks pass.

Checklist

BEFORE

AFTER

Required Checks

• Documentation is updated (if applicable)
• Files follow existing naming conventions
• Changes are backwards compatible (if applicable)
• Tests added for new functionality (if applicable)

Required Local Checks

The following local-safe validation commands must pass before merging:

• Local validation aggregate: npm run validate:local
• Documentation validation (if docs changed): npm run validate:docs
• Spell checking: npm run spell-check
• Link validation: npm run lint:md-links

Security Considerations

• This PR does not contain any sensitive or NDA information
• Any new dependencies have been reviewed for security issues
• Security-related scripts follow the principle of least privilege

Additional Notes

This PR prepares the UI foundation for Issue #1317. Once the dynamically generated collection detail pages are created, they can simply import <MaturityBadge maturity={frontMatter.maturity} size="md" /> to display consistent, accessible badges on those pages as well.

[Bill Berry (WilliamBerryiii)]

Thank you for this contribution, pratik wayase (@PratikWayase). Extracting the maturity badge into a reusable component improves consistency, and the focused tests cover the recognized variants well; I also confirmed that npm run validate:docs and npm run lint:md-links pass against this head.

I am requesting changes for one accessibility blocker and two functional concerns detailed inline. Please also either complete the collection-detail-page criteria from #1318 or adjust the issue scope and Fixes linkage, then record the passing validation and clear the blocked merge state before merge. Comment on any of the suggestions if you would like to discuss the implementation path.

[pratik wayase (PratikWayase)]

Hii Bill Berry (@WilliamBerryiii), I've resolved all three blocks, replaced the title attribute with an accessible CSS-only tooltip, fixed the dead click zone viz pointer events, and added a strict unknown fallback state with dev guardrails instead of silently defaulting to experimental.

This PR focuses solely on UI/UX, accessibility, and CSS layout improvements for maturity badges The dynamic YAML collection page generation will be scoped into a separate PR to keep history clean. All 95 tests and validation checks are passing against the head.