docs: fix banner accessibility and hover color contrast

[naorpeled]

Summary

• Apply WCAG AA compliant background colors for the announcement banner in both light and dark modes
• Fix dark mode banner color from #1e3a5f (1.49:1 distinction vs header) to #2563eb (3.31:1 distinction)
• Fix link hover/focus color staying white instead of changing to accent color (which was invisible against the blue banner)

Accessibility

Mode	Banner BG	White Text Contrast	WCAG AA	Header Distinction
Light	#1d4ed8	6.70:1	PASS	2.66:1
Dark	#2563eb	5.17:1	PASS	3.31:1

Test plan

• Verify banner text is readable in light mode
• Verify banner text is readable in dark mode
• Verify banner link hover state stays white in both modes
• Verify banner is visually distinct from header in both modes

🤖 Generated with Claude Code

[qodo-free-for-open-source-projects]

Review Summary by Qodo

Fix banner accessibility and hover color contrast for WCAG AA compliance

📝 Documentation ✨ Enhancement

Walkthroughs

Description

• Apply WCAG AA compliant banner colors for light and dark modes
• Fix dark mode banner background from #1e3a5f to #2563eb for better contrast
• Fix banner link hover/focus colors to stay white instead of inheriting accent color
• Ensure banner is visually distinct from header with proper color contrast ratios

Diagram

flowchart LR
  A["Banner Styling"] --> B["Light Mode: #1d4ed8"]
  A --> C["Dark Mode: #2563eb"]
  A --> D["Link Colors"]
  D --> E["Hover/Focus: White"]
  B --> F["6.70:1 Contrast"]
  C --> G["5.17:1 Contrast"]

Loading

File Changes

1. docs/docs/css/custom.css Accessibility, styling +15/-0

Add WCAG AA compliant banner colors and link styling

• Added .md-banner selector with light mode background color #1d4ed8
• Added dark mode .md-banner selector with background color #2563eb
• Added banner link styling to maintain white color on hover and focus states
• Ensured links use currentColor and underline decoration for accessibility

docs/docs/css/custom.css

---

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0) 📎 Requirement gaps (0)

1. Banner fg not explicit 🐞 Bug ✓ Correctness

Description

The banner background is set, but no explicit foreground/text color is defined for .md-banner, and
link color is set to currentColor (which depends on the banner’s inherited text color). This makes
banner readability/contrast depend on upstream theme defaults and increases the chance of a future
theme/palette change causing low-contrast text/links.

Code

docs/docs/css/custom.css[R109-121]

+.md-banner {
+    background-color: #1d4ed8;
+}
+
+[data-md-color-scheme="slate"] .md-banner {
+    background-color: #2563eb;
+}
+
+.md-banner .md-typeset a,
+.md-banner .md-typeset a:hover,
+.md-banner .md-typeset a:focus {
+    color: currentColor;
+    text-decoration: underline;

Evidence

custom.css sets only .md-banner background colors and makes banner links inherit currentColor,
but never sets .md-banner { color: ... }, so the computed banner/link foreground depends on
whatever .md-banner (or its parents) inherit from the theme. The banner content includes plain
text and an <a> in the announce block, so both are impacted by the banner’s inherited color.

docs/docs/css/custom.css[109-122]
docs/overrides/main.html[1-5]
docs/mkdocs.yml[46-66]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The PR sets `.md-banner` background colors but does not set an explicit text/foreground color for the banner. Since banner links are set to `color: currentColor`, link color will track whatever inherited text color the theme applies to the banner.

### Issue Context
The announcement content is defined in `docs/overrides/main.html` and includes both plain text and an `<a>` element. Both should remain readable regardless of upstream theme defaults.

### Fix Focus Areas
- docs/docs/css/custom.css[1-18]
- docs/docs/css/custom.css[109-122]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Hardcoded banner colors 🐞 Bug ⛯ Reliability

Description

Banner colors are hardcoded hex values rather than being expressed via CSS variables like the rest
of the site palette. This increases maintenance overhead and creates a higher risk of palette/theme
updates causing the banner to drift from intended branding/contrast targets.

Code

docs/docs/css/custom.css[R109-115]

+.md-banner {
+    background-color: #1d4ed8;
+}
+
+[data-md-color-scheme="slate"] .md-banner {
+    background-color: #2563eb;
+}

Evidence

The file already centralizes key palette choices via CSS variables in :root and
[data-md-color-scheme="slate"], but the new banner background colors are introduced as literals
(#1d4ed8, #2563eb) instead of being derived from variables or introducing banner-specific
variables.

docs/docs/css/custom.css[1-12]
docs/docs/css/custom.css[109-115]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
Banner background colors are hardcoded hex values. The rest of the file already uses CSS variables to define the palette, so banner colors should follow the same pattern to avoid drift.

### Issue Context
Light mode currently repeats `#1d4ed8` (also present as `--md-accent-fg-color`). Dark mode introduces `#2563eb` without any variable definition.

### Fix Focus Areas
- docs/docs/css/custom.css[1-18]
- docs/docs/css/custom.css[109-115]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

ⓘ The new review experience is currently in Beta. Learn more

[Copilot]

Pull request overview

Updates the MkDocs Material announcement banner styling to improve accessibility by ensuring the banner background is visually distinct in both light/dark modes and that banner links remain readable on hover/focus.

Changes:

• Set explicit announcement banner background colors for default and slate (dark) schemes.
• Force banner link color (including hover/focus) to inherit the banner text color for consistent contrast, and underline links for clarity.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[adrian-kinda-bot]

@CodiumAI-Agent /improve

[naorpeled]

@CodiumAI-Agent /review

[naorpeled]

@qodo-ai /review