Skip to content

Enhance accessibility compliance in themes and a11y tests#281

Merged
yamcodes merged 6 commits intomainfrom
264-fix-color-contrast-accessibility-violation---shiki-syntax-highlighting-and-fumadocs-ui-muted-text
Nov 5, 2025
Merged

Enhance accessibility compliance in themes and a11y tests#281
yamcodes merged 6 commits intomainfrom
264-fix-color-contrast-accessibility-violation---shiki-syntax-highlighting-and-fumadocs-ui-muted-text

Conversation

@yamcodes
Copy link
Owner

@yamcodes yamcodes commented Nov 4, 2025

  • Updated light and dark theme styles to improve WCAG AA compliance by adjusting color contrasts for muted foregrounds.
  • Introduced high-contrast themes in the configuration for better accessibility.
  • Removed the 'color-contrast' rule from a11y tests to streamline known issues with third-party libraries.

This update aims to enhance the overall accessibility of the application, ensuring a better experience for users with visual impairments.

Closes #264

Summary by CodeRabbit

  • Style

    • Updated muted text colors and added high-contrast overrides for light and dark themes; included the overrides in global styles.
  • Accessibility

    • Switched MDX rendering to high-contrast themes to meet WCAG AA contrast standards and improve readability.
  • Tests

    • Adjusted ordering of accessibility rules in the smoke test (no change to overall test behavior).

- Updated light and dark theme styles to improve WCAG AA compliance by adjusting color contrasts for muted foregrounds.
- Introduced high-contrast themes in the configuration for better accessibility.
- Removed the 'color-contrast' rule from a11y tests to streamline known issues with third-party libraries.

This update aims to enhance the overall accessibility of the application, ensuring a better experience for users with visual impairments.
@changeset-bot
Copy link

changeset-bot bot commented Nov 4, 2025

⚠️ No Changeset found

Latest commit: 2235683

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

@vercel
Copy link

vercel bot commented Nov 4, 2025

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Preview Comments Updated (UTC)
arkenv Ready Ready Preview Comment Nov 5, 2025 7:48am

@github-actions github-actions bot added www Improvements or additions to arkenv.js.org tests This issue or PR is about adding, removing or changing tests labels Nov 4, 2025
@coderabbitai
Copy link
Contributor

coderabbitai bot commented Nov 4, 2025

Walkthrough

Updated muted-foreground CSS variables for light and dark themes, added fumadocs-specific overrides, switched MDX code themes to high-contrast variants, imported the new overrides, and re-enabled the Axe "color-contrast" rule in accessibility tests.

Changes

Cohort / File(s) Summary
Theme CSS variables
apps/www/app/styles/theme/light.css, apps/www/app/styles/theme/dark.css
Increased contrast of --muted-foreground HSL values and added WCAG AA contrast comments.
Fumadocs overrides
apps/www/app/styles/components/fd.css
Added --color-fd-muted-foreground in :root and .dark with WCAG AA-compliant HSL values and comments.
Global CSS import
apps/www/app/globals.css
Imported ./styles/components/fd.css to include the new fumadocs overrides in the cascade.
MDX / syntax theme config
apps/www/source.config.ts
Switched MDX syntax themes to github-light-high-contrast and github-dark-high-contrast with a WCAG AA note.
Accessibility tests
tooling/playwright-www/tests/a11y.test.ts
Re-enabled color-contrast checks in the a11y smoke test (adjusted disableRules).

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant Dev
  participant Repo
  participant Build as Site Build
  participant CSS as CSS (theme + fd overrides)
  participant MDX as MDX Renderer
  participant A11Y as Playwright A11y Test

  Dev->>Repo: push commit (theme CSS, fd.css, globals import, source.config.ts, tests)
  Repo->>Build: trigger build
  Build->>CSS: load theme files + fd overrides (globals.css imports)
  Build->>MDX: render MDX using high-contrast themes
  MDX-->>Build: code blocks with high-contrast colors
  Build->>A11Y: run accessibility tests (color-contrast enabled)
  A11Y-->>Build: report issues / pass results
  Note right of A11Y `#DDEEFF`: "color-contrast" now validated (WCAG AA)
Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

  • Verify contrast ratios of new HSL values in light.css, dark.css, and fd.css.
  • Confirm github-light-high-contrast / github-dark-high-contrast themes exist and render in MDX.
  • Run Playwright a11y tests locally to confirm color-contrast passes.

Possibly related PRs

  • Accessibility tests #259 — Modified the Playwright a11y test file (tooling/playwright-www/tests/a11y.test.ts); closely related to re-enabling color-contrast.

Poem

🐰 I nibbled muted shades till letters shone,

Tweaked themes and vars so contrast is grown,
Imports stitched in, tests now wake and light,
Docs sing clear by day and every night.

Pre-merge checks and finishing touches

✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately captures the main objective of the PR—enhancing accessibility compliance in themes and a11y tests to address WCAG AA color contrast violations.
Linked Issues check ✅ Passed The PR addresses issue #264 by adjusting muted foreground colors for WCAG AA compliance (6.13:1 and 8.88:1 contrast), using high-contrast Shiki themes, and reordering a11y test rules.
Out of Scope Changes check ✅ Passed All changes are directly related to addressing color contrast accessibility violations specified in issue #264; no unrelated modifications detected.
✨ Finishing touches
  • 📝 Generate docstrings
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch 264-fix-color-contrast-accessibility-violation---shiki-syntax-highlighting-and-fumadocs-ui-muted-text

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 57dbe42 and 2235683.

📒 Files selected for processing (1)
  • tooling/playwright-www/tests/a11y.test.ts (1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
  • tooling/playwright-www/tests/a11y.test.ts
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
  • GitHub Check: test-e2e (e2e)
  • GitHub Check: test-e2e (a11y)

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

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

Actionable comments posted: 2

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f2fddd7 and 9d2148b.

📒 Files selected for processing (4)
  • apps/www/app/styles/theme/dark.css (1 hunks)
  • apps/www/app/styles/theme/light.css (1 hunks)
  • apps/www/source.config.ts (1 hunks)
  • tooling/playwright-www/tests/a11y.test.ts (0 hunks)
💤 Files with no reviewable changes (1)
  • tooling/playwright-www/tests/a11y.test.ts
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
  • GitHub Check: test-e2e (e2e)
  • GitHub Check: test-e2e (a11y)
🔇 Additional comments (1)
apps/www/source.config.ts (1)

166-168: Theme identifiers verified—code is correct.

The Shiki theme identifiers github-light-high-contrast and github-dark-high-contrast are valid and included in Shiki's bundled themes. The accessibility-focused theme selection is appropriate.

yamcodes and others added 3 commits November 5, 2025 12:16
- Updated muted foreground colors in light and dark themes to improve WCAG AA compliance, ensuring better contrast ratios.
- Introduced a new CSS variable for muted foreground colors in the `fd.css` file to maintain accessibility standards across different themes.

This update aims to enhance the overall accessibility of the application, providing a better experience for users with visual impairments.
…on---shiki-syntax-highlighting-and-fumadocs-ui-muted-text
- Updated muted foreground color contrast ratios in light and dark themes to improve WCAG AA compliance.
- Added fd.css to global styles for better theme integration.

This update aims to further enhance the accessibility of the application, ensuring a better experience for users with visual impairments.
Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

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

Actionable comments posted: 0

🧹 Nitpick comments (1)
apps/www/app/styles/components/fd.css (1)

4-16: CSS overrides are WCAG AA compliant with correct variable naming; update inline contrast ratio comments for accuracy.

The --color-fd-muted-foreground variable name is correct and confirmed in fumadocs documentation. The light mode color (hsl(240 4% 40%)) achieves 6.03:1 contrast on white and the dark mode color (hsl(240 5% 70%)) achieves 9.63:1 contrast on black, both exceeding the WCAG AA minimum of 4.5:1.

However, the inline comments state 6.13:1 and 8.88:1 respectively—update these to reflect the actual calculated values (6.03:1 and 9.63:1) for documentation accuracy.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 26c628e and 57dbe42.

📒 Files selected for processing (2)
  • apps/www/app/globals.css (1 hunks)
  • apps/www/app/styles/components/fd.css (1 hunks)
🔇 Additional comments (1)
apps/www/app/globals.css (1)

8-8: CSS import placement looks good.

The fd.css import is appropriately positioned in the cascade—after theme and alert styles but before base styles—ensuring fumadocs-specific overrides are applied and available to downstream styles without being inadvertently overridden.

…on---shiki-syntax-highlighting-and-fumadocs-ui-muted-text
@yamcodes yamcodes merged commit c6fb702 into main Nov 5, 2025
15 checks passed
@yamcodes yamcodes deleted the 264-fix-color-contrast-accessibility-violation---shiki-syntax-highlighting-and-fumadocs-ui-muted-text branch November 5, 2025 09:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

tests This issue or PR is about adding, removing or changing tests www Improvements or additions to arkenv.js.org

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Fix color-contrast accessibility violation - shiki syntax highlighting and fumadocs-ui muted text

1 participant