Fix a11y: improve sitemap link color contrast to meet WCAG AA

[huangkevin-apr]

Description of Problem

This PR addresses an accessibility issue reported by automated accessibility checkers (IBM Equal Access Accessibility Checker), several contrast-related accessibility violations were reported.:

Text contrast is less than the WCAG AA minimum requirements
Affected text size: ~14.4px, weight: 400

The issue occurs in the SiteMap section, where link text uses a low-contrast color against the background, making it difficult to read for users with low vision or contrast sensitivity.

The sitemap links currently use the CSS variable --vt-c-text-2, which does not provide sufficient contrast against the background to satisfy WCAG 2.1 Success Criterion 1.4.3 (Contrast – Minimum) for normal text.

Why is this important?
When text and its background colors have less than a 4.5 to 1 contrast ratio it can be difficult for people with moderately low vision to read the text without contrast-enhancing technology.

Proposed Solution

This PR increases the contrast of sitemap links by switching to a higher-contrast text color:

#sitemap .vt-link {
  font-size: 0.9em;
- color: var(--vt-c-text-2);
+ /* increased contrast for better legibility (WCAG 1.4.3) */
+ color: var(--vt-c-text-1);
}

Fix Before:

Fix After:

Verification

• Re-ran IBM Accessibility Checker after applying the patch.
• Confirmed that the previously reported contrast-related accessibility violations no longer occur.

Additional Information

The patch submitted in this PR was generated by A11YRepair, an automated Web Accessibility repair tool that I developed to address common accessibility violations in web applications.
The generated fixes were manually reviewed and validated before submission.

[netlify]

✅ Deploy Preview for vuejs ready!

Name	Link
🔨 Latest commit	c5fd5d7
🔍 Latest deploy log	https://app.netlify.com/projects/vuejs/deploys/695c9df5d7f29b0008c142d2
😎 Deploy Preview	https://deploy-preview-3327--vuejs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[AloisSeckar]

While I understand the relevance, especially when A11Y is promoted even in the docs themselves, I don't like the proposed solution that match. I would rather suggest trying to some combination of colors, that would fit better. Not just having the headlines and links the same color.

Also, can you test, if the problem happens in dark mode as well? Or is this sufficient accoding to guidelines?

[huangkevin-apr]

While I understand the relevance, especially when A11Y is promoted even in the docs themselves, I don't like the proposed solution that match. I would rather suggest trying to some combination of colors, that would fit better. Not just having the headlines and links the same color.

Also, can you test, if the problem happens in dark mode as well? Or is this sufficient accoding to guidelines?

Thanks for the helpful feedback!
I provided your repair suggestions to A11YRepair and regenerated the patch.

The reasoning process of A11YRepair:

An analysis of the A11Y Bug Report and the accompanying screenshot reveals a widespread text contrast issue across the website's footer. All flagged elements, from ELEMENT_3 to ELEMENT_36, are anchor tags (<a>) within the sitemap section.\n\n### Bug Analysis\n\nThe core issue is a violation of the text_contrast_sufficient rule. The report indicates that the text color #757575 on a background of #f9f9f9 results in a contrast ratio of 4.40:1. This is below the WCAG AA minimum requirement of 4.5:1 for normal-sized text.\n\nLooking at the provided source code, the cause is located in /.vitepress/theme/components/SiteMap.vue. The following CSS rule is responsible for styling the links in the sitemap:\n\ncss\n#sitemap .vt-link {\n font-size: 0.9em;\n color: var(--vt-c-text-2);\n}\n\n\nHere, the CSS variable --vt-c-text-2 corresponds to the problematic color #757575, and the background for the #sitemap section is set with --vt-c-bg-soft, which corresponds to #f9f9f9.\n\nThe bug report also contains a specific user preference: not to make the links the same color as the section headings, which use the --vt-c-text-1 variable.\n\n### Bug Fix Strategy\n\nTo resolve this, I will modify the CSS rule in /.vitepress/theme/components/SiteMap.vue. The goal is to increase the text contrast while respecting the design preference for the links to be visually distinct from the headings.\n\nInstead of hardcoding a new color, which would be brittle and not theme-friendly (especially for dark mode), I will base the link color on the main text color variable, --vt-c-text-1. This variable is guaranteed to have sufficient contrast. To differentiate the links from the headings, I will apply an opacity of 0.75. This will make the links slightly lighter than the headings but dark enough to meet accessibility standards, and it will work correctly in both light and dark modes.\n\nThis approach provides a robust, theme-aware solution that fixes the accessibility violation and addresses the user's feedback.\n\n

Refined Patch:

 #sitemap .vt-link {
   font-size: 0.9em;
-  color: var(--vt-c-text-2);
+  color: var(--vt-c-text-1);
+  opacity: 0.75;
 }

Screenshot

Fix Before:

Fix After:

Violation Report

Fix Before:

Fix After:

Here we can see that 34 contrast-related violations have been resolved.

Dark Mode

I have run the A11y Checker and confirmed that this section of text elements (34 elements) contains no accessibility violations.