Fix Color Contrast In Shiki & Fumadocs For Accessibility

by Admin 57 views
Fixing Color Contrast Accessibility Violations in Shiki Syntax Highlighting and Fumadocs-UI Muted Text

Hey guys! Let's dive into a crucial topic for web accessibility: color contrast. We're going to explore how to fix color contrast violations specifically in Shiki syntax highlighting and fumadocs-ui muted text. This is super important because ensuring good color contrast makes our websites more usable for everyone, especially those with visual impairments.

The Issue: Color Contrast Accessibility Violation

Currently, the accessibility tests for documentation pages have the color-contrast rule disabled. Why? Because there are violations coming from both syntax highlighting and the styling of muted text. This means some text isn't standing out enough against its background, making it hard to read. We need to address this to create a better experience for our users.

The Problem Areas

There are two main culprits causing these color contrast violations:

  1. Shiki Syntax Highlighting: Shiki is awesome for making code snippets look pretty with different colors, but the inline CSS variables (--shiki-light and --shiki-dark) it uses sometimes don't meet the WCAG 2 AA minimum contrast ratio of 4.5:1. This ratio is the golden standard for ensuring readability. In simpler terms, some of the highlighted code might be too similar in color to the background, making it difficult to read, especially for people with visual impairments. It’s crucial that we ensure that code, which is often a core part of documentation, is easily accessible.
  2. Fumadocs-UI Muted Foreground: Fumadocs-ui uses muted foreground colors for secondary text, like in code block captions and card descriptions. These colors (text-fd-muted-foreground, text-sm.text-fd-muted-foreground) often fall slightly below that 4.5:1 contrast threshold. Think of muted text as the less important stuff, but it still needs to be readable! This includes things like captions under code blocks (figcaption.flex-1.truncate) and descriptions on cards (p.text-fd-muted-foreground). Ignoring these elements can lead to a frustrating user experience, as users may struggle to differentiate between primary and secondary information. We want to guide our users smoothly through the content, and proper contrast is a key element in achieving this.

Impact: This is a serious accessibility violation. Failing to meet color contrast standards can exclude users with low vision or color blindness, which is not cool. By addressing this, we are making a commitment to inclusivity and ensuring that our documentation is accessible to a wider audience. Remember, accessibility is not just a feature; it’s a fundamental aspect of good design and development practices.

Where Are These Issues Happening?

These color contrast issues are popping up on various documentation pages, including:

  • Quickstart page (/docs/quickstart)
  • Main docs pages (/docs, /docs/examples, /docs/morphs)
  • Integration pages (/docs/integrations/vscode, /docs/integrations/jetbrains)

We've even got test files highlighting these problems:

  • tooling/playwright-www/tests/quickstart.test.ts:192
  • tooling/playwright-www/tests/docs-navigation.test.ts:202, 233
  • tooling/playwright-www/tests/accessibility.test.ts:208

These files serve as crucial markers in our quest to squash these accessibility bugs. They provide a starting point for developers to investigate and implement solutions. Regularly running these tests will also help us ensure that future changes don't inadvertently reintroduce these issues. Consider these tests as our guardians of accessibility!

The Current Workaround

For now, we've temporarily disabled the color-contrast rule in our accessibility tests. This is a quick fix to prevent failing builds, but it's not a solution. We need to properly address the underlying issues. Think of this as putting a bandage on a wound – it stops the bleeding, but we still need to heal the injury.

disableRules: ["color-contrast"]

This temporary measure allows us to continue development without being blocked by failing accessibility tests. However, it's essential to remember that this is a temporary solution. We must prioritize implementing a permanent fix to ensure our documentation meets accessibility standards. The ultimate goal is to remove this line of code and have all our tests passing with the color-contrast rule enabled.

Potential Solutions: Let's Get Fixing!

Alright, let's brainstorm some ways we can tackle these color contrast violations. Here are a few potential solutions we can explore:

  1. Theme Color Adjustment: This involves tweaking the Shiki theme colors to guarantee a 4.5:1 contrast in both light and dark modes. It's like giving our color palette a tune-up to make sure everything harmonizes well. This approach requires careful consideration of the existing design aesthetic. We need to find colors that not only meet the contrast requirements but also maintain the visual appeal of our documentation. It's a balancing act between accessibility and aesthetics. One way to approach this is to use color contrast checkers, which are readily available online. These tools can help us identify color combinations that meet the WCAG guidelines. Experimentation and collaboration with designers are key here. We want to create a color scheme that is both accessible and visually pleasing.
  2. Fumadocs-UI Styling Override: We can override the muted foreground colors in fumadocs-ui to meet those contrast requirements. This is like giving a little nudge to specific elements to make them stand out more. This could involve modifying the CSS variables or creating custom styles for the affected elements. When overriding styles, it's important to be mindful of specificity. We want to ensure that our overrides are applied correctly and don't inadvertently affect other elements on the page. Using specific selectors and testing our changes thoroughly is crucial in this process. Furthermore, we should document these overrides clearly so that other developers understand why they were implemented and how they work.
  3. Custom Syntax Highlighting: We could use a custom Shiki configuration with higher-contrast color schemes. This is like choosing a completely new set of paints that are guaranteed to be vibrant and readable. This approach gives us greater control over the color palette used for syntax highlighting. We can carefully select colors that meet the contrast requirements while still providing a visually appealing coding experience. This may involve creating our own Shiki theme or adapting an existing one. The key here is to test the theme thoroughly in both light and dark modes to ensure that all code elements have sufficient contrast. We should also consider providing users with the option to choose between different high-contrast themes to cater to individual preferences.
  4. CSS Custom Properties: Adjusting CSS variables for muted foreground colors can improve contrast while maintaining the design intent. This is like fine-tuning the colors we already have to make them work better together. This approach allows us to make targeted adjustments to the muted foreground colors without completely overhauling the existing styles. By manipulating the CSS variables, we can experiment with different color combinations and find a balance between contrast and visual aesthetics. This method offers a flexible way to address the color contrast issues while minimizing the impact on the overall design. It's also a more maintainable solution compared to directly modifying the CSS styles.

Each of these solutions has its own set of trade-offs. For instance, adjusting theme colors might have a broad impact, while overriding styles might be more targeted but could also lead to maintenance challenges in the long run. Custom syntax highlighting gives us maximum control but requires more effort to set up and maintain. The best approach will likely involve a combination of these techniques, tailored to the specific needs of our project.

Related Efforts and Future Tracking

This issue is already being tracked in our accessibility tests. You'll see this comment:

// TODO: Fix color-contrast - shiki syntax highlighting spans and fumadocs-ui muted foreground text
// Code syntax highlighting uses theme colors that may not always meet 4.5:1 contrast in both themes

This comment serves as a reminder that this is an ongoing effort. It also helps other developers understand the context of the issue and the work that has already been done. Maintaining clear and informative comments in our codebase is crucial for collaboration and knowledge sharing. It ensures that everyone is on the same page and can contribute effectively to solving the problem. Furthermore, we should regularly review these comments to ensure they are still relevant and up-to-date.

Wrapping Up: Accessibility for All

Fixing these color contrast violations is a big step towards making our documentation more accessible. Remember, accessibility isn't just about meeting standards; it's about creating a welcoming and inclusive experience for all users. By addressing these issues, we're ensuring that everyone can easily access and understand our content. So, let's roll up our sleeves and get to work on making the web a more accessible place!