Mintlify Accessibility Checklist 2026 | WCAG 2.1 AA Compliance

Mintlify's default Prism syntax theme renders comments in #6e7781 on a #f6f8fa background. This measures 3.7:1 contrast, below the 4.5:1 required for normal-size text. Code comments in API documentation carry critical context (parameter explanations, deprecation notes, security warnings) that low-vision users cannot read. The same comment colour is used in cURL, JavaScript, Python, and Ruby snippets, multiplying the impact.

/* Default Mintlify Prism light theme */
.token.comment, .token.prolog, .token.doctype, .token.cdata { color: #6e7781; }

/* Override in global.css */
.token.comment, .token.prolog, .token.doctype, .token.cdata { color: #57606a; }
/* Dark mode override */
.dark .token.comment { color: #8b949e; }

The Mintlify search modal opens with Cmd+K or by clicking the search bar. Focus correctly moves to the search input on open, but pressing Escape does not close the modal. Keyboard users have to either Tab to the close button (which is the last focusable element) or click outside the modal. Some Mintlify versions also fail to return focus to the trigger after the modal closes.

// No Escape binding
// Modal opens with Cmd+K, closes only on outside click

// custom.js loaded via docs.json customJs
let searchTrigger = null;
window.addEventListener('mintlify:search-open', () => { searchTrigger = document.activeElement; });
window.addEventListener('keydown', e => {
  if (e.key === 'Escape' && document.querySelector('[aria-modal=true].search-modal')) {
    window.MintlifySearch.close();
    searchTrigger?.focus();
  }
});

Mintlify auto-renders an interactive API playground from the OpenAPI spec linked in docs.json. Each parameter becomes a form input with the parameter name shown as a span above it, but the input itself has no <label> association and no aria-label. Screen reader users hear 'edit text' with no parameter name. The pattern fails WCAG 3.3.2 Labels or Instructions because the parameter name is not programmatically determinable.

<div class="playground-param">
  <span class="param-name">user_id</span>
  <input type="text" class="param-input">
</div>

<div class="playground-param">
  <label for="param-user-id" class="param-name">user_id <span class="required">*</span></label>
  <input type="text" id="param-user-id" class="param-input" aria-describedby="param-user-id-desc" required>
  <small id="param-user-id-desc">UUID of the user to fetch</small>
</div>

The Mintlify AI chat widget opens as a slide-in panel from the bottom-right of the viewport. The panel renders without role='dialog', without aria-modal, and without moving focus into the chat input. Screen reader users get no notification that a panel opened. The widget also does not trap focus, so Tab from the chat input lands on the next page element behind the still-open panel.

<div class="mintlify-ai-chat" style="display:block">
  <div class="chat-header">Ask AI</div>
  <input class="chat-input" placeholder="Type your question">
</div>

<div class="mintlify-ai-chat" role="dialog" aria-modal="true" aria-labelledby="chat-title">
  <h2 id="chat-title" class="chat-header">Ask AI</h2>
  <button aria-label="Close chat" class="close-chat">x</button>
  <label for="chat-input" class="sr-only">Type your question</label>
  <input id="chat-input" class="chat-input">
</div>

The Mintlify sidebar groups navigation items into expandable sections (Get Started, Guides, API Reference, etc.). The expand/collapse trigger is rendered as a span with onclick rather than a button. Keyboard users cannot focus the trigger with Tab, and screen reader users hear no indication that the section is expandable.

<span class="sidebar-section-toggle" onclick="toggleSection(this)">
  Guides
  <svg class="chevron">...</svg>
</span>

<button type="button" class="sidebar-section-toggle" aria-expanded="true" aria-controls="section-guides">
  Guides
  <svg class="chevron" aria-hidden="true">...</svg>
</button>
<ul id="section-guides">...</ul>

Every Mintlify code block ships with a copy-to-clipboard button in the top-right corner. The button is an icon-only control with no aria-label, no visible text, and no tooltip readable by screen readers. Users hear 'button' with no purpose. The same button after activation often does not announce 'Copied!' to screen readers.

<button class="code-copy-btn">
  <svg class="copy-icon">...</svg>
</button>

<button class="code-copy-btn" aria-label="Copy code to clipboard">
  <svg class="copy-icon" aria-hidden="true">...</svg>
  <span class="sr-only copy-status" aria-live="polite"></span>
</button>
<script>btn.addEventListener('click', () => { navigator.clipboard.writeText(code); btn.querySelector('.copy-status').textContent = 'Copied'; setTimeout(() => btn.querySelector('.copy-status').textContent = '', 2000); });</script>

Mintlify ships with a dark-mode toggle in the top navigation. On older deployments the toggle is page-local: switching to dark mode applies only to the current page and reverts to light when navigating to another doc. Users with light sensitivity who rely on dark mode for accessibility are forced to re-toggle on every page load. WCAG 1.4.6 (Contrast Enhanced AAA) and the broader user-needs argument both apply.

// docs.json
{
  "theme": { "defaultMode": "light" }
}

// docs.json
{
  "theme": {
    "defaultMode": "system",
    "persistMode": "localStorage",
    "respectSystem": true
  }
}

The Mintlify auto-generated API reference page uses H1 for the endpoint name, then jumps to H4 for parameter section headings, skipping H2 and H3. The same pattern affects the response examples. Screen reader users navigating by heading level skip past content because the hierarchy implies content does not exist between levels.

<h1>POST /users</h1>
<h4>Request body</h4>
<h4>Responses</h4>

<h1>POST /users</h1>
<h2>Request body</h2>
<h3>Required parameters</h3>
<h3>Optional parameters</h3>
<h2>Responses</h2>
<h3>200 OK</h3>
<h3>400 Bad Request</h3>