> ## Documentation Index
> Fetch the complete documentation index at: https://learn.cleftnotes.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Accessibility Templates

> Reusable accessibility patterns and templates for EU Accessibility Act compliance (WCAG 2.1 AA)

<Warning>
  **Internal Documentation**: This page contains templates and patterns for maintaining accessibility compliance across all documentation. Not intended for end users.
</Warning>

## EU Accessibility Act Compliance Templates

As of June 28, 2025, all digital services must comply with EU Accessibility Act requirements. These templates ensure WCAG 2.1 AA compliance across all documentation.

## Skip Navigation Template

Add to pages with multiple sections for keyboard navigation:

```mdx theme={null}
<nav role="navigation" aria-label="Page navigation" className="skip-links">
  <a href="#main-content" className="skip-link">Skip to main content</a>
  <a href="#%F0%9F%86%98-getting-help" className="skip-link">Skip to Getting Help</a>
  <a href="#account-billing" className="skip-link">Skip to Account & Billing</a>
</nav>
```

## Accessible Card Templates

### Standard Card with Link

```mdx theme={null}
<Card 
  title="Card Title" 
  icon="icon-name" 
  href="/destination-page"
  aria-label="Navigate to destination page for specific action"
>
  Brief description of what this card does
</Card>
```

### Card Group with Proper Labels

```mdx theme={null}
<CardGroup cols={2} role="group" aria-label="Support options">
  <Card 
    title="Contact Support" 
    icon="envelope" 
    href="/user-guides/contact-support"
    aria-label="Contact our support team via email"
  >
    Get help from our team within 24 hours
  </Card>
  
  <Card 
    title="FAQ" 
    icon="circle-question" 
    href="/user-guides/faq"
    aria-label="Browse frequently asked questions"
  >
    Find quick answers to common questions
  </Card>
</CardGroup>
```

### External Link Card

```mdx theme={null}
<Card 
  title="Download App" 
  icon="download" 
  href="https://apps.apple.com/us/app/cleft-notes/id6479458038"
  aria-label="Download Cleft app from Apple App Store (opens in new window)"
>
  Get Cleft for iOS, iPadOS, and macOS
</Card>
```

## Accessible Accordion Templates

### Standard Accordion

```mdx theme={null}
<Accordion 
  title="Question or Topic" 
  role="button"
  aria-expanded="false"
  aria-controls="accordion-content-unique-id"
>
  Content that answers the question or explains the topic.
</Accordion>
```

### Accordion Group

```mdx theme={null}
<AccordionGroup role="region" aria-label="Frequently asked questions about account setup">
  <Accordion 
    title="How do I create an account?" 
    role="button"
    aria-expanded="false"
    aria-controls="create-account-content"
  >
    Step-by-step instructions for account creation.
  </Accordion>
  
  <Accordion 
    title="How do I reset my password?" 
    role="button"
    aria-expanded="false"
    aria-controls="reset-password-content"
  >
    Password reset instructions and troubleshooting.
  </Accordion>
</AccordionGroup>
```

## Heading Hierarchy Template

Use proper heading hierarchy with ID anchors for keyboard navigation:

```mdx theme={null}
## Main Section {#main-section}

Content for the main section.

### Subsection {#subsection}

Content for subsection.

#### Details {#details}

Detailed content.
```

## Accessible Link Templates

### Internal Links

```mdx theme={null}
<!-- Good -->
[Learn about custom instructions](/user-guides/custom-instructions)
[View pricing details](/user-guides/upgrade-to-plus)

<!-- Avoid -->
[Click here](#)
[Read more](#)
```

### External Links with Context

```mdx theme={null}
<!-- Good -->
[Download from Apple App Store](https://apps.apple.com/us/app/cleft-notes/id6479458038) (opens in new window)
[Contact support via email](mailto:hello@cleftnotes.com)

<!-- Avoid -->
[Download here](https://apps.apple.com/us/app/cleft-notes/id6479458038)
[Email us](mailto:hello@cleftnotes.com)
```

## Screen Reader Only Text

For additional context that helps screen reader users:

```mdx theme={null}
<span className="sr-only">
  Additional context for screen readers
</span>
```

## Form Templates (Future Use)

### Accessible Form Fields

```mdx theme={null}
<label htmlFor="email-input">
  Email Address (required)
</label>
<input 
  id="email-input"
  type="email" 
  required 
  aria-describedby="email-help email-error"
/>
<div id="email-help">
  We'll never share your email address
</div>
<div id="email-error" role="alert" aria-live="polite">
  <!-- Error message appears here -->
</div>
```

## Color and Contrast Guidelines

### Acceptable Color Combinations

* **Primary Orange (#d44426)** on white background ✅
* **White text** on Primary Orange background ✅
* **Dark gray (#2d3748)** on white background ✅
* **White text** on dark gray background ✅

### Test Your Colors

* Use [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
* Target: 4.5:1 for normal text, 3:1 for large text
* Test in high contrast mode

## Testing Checklist

Before publishing any page, verify:

* [ ] All Cards have descriptive `aria-label` attributes
* [ ] All Accordions have `role="button"` and `aria-expanded`
* [ ] Headings follow proper hierarchy (h1 → h2 → h3)
* [ ] All links have descriptive text
* [ ] Skip navigation links are present for multi-section pages
* [ ] Color contrast meets WCAG AA standards (4.5:1)
* [ ] Page works with keyboard-only navigation
* [ ] Screen reader announces content logically

## Common Accessibility Issues to Avoid

### ❌ Bad Examples

```mdx theme={null}
<!-- Missing aria-label -->
<Card title="Support" icon="help" href="/support">

<!-- Generic accordion -->
<Accordion title="Question">

<!-- Generic link text -->
[Click here](#)

<!-- Missing heading hierarchy -->
# Page Title
### Subsection (skipped h2)
```

### ✅ Good Examples

```mdx theme={null}
<!-- Proper aria-label -->
<Card title="Support" icon="help" href="/support" aria-label="Get help and support from our team">

<!-- Accessible accordion -->
<Accordion title="How do I reset my password?" role="button" aria-expanded="false">

<!-- Descriptive link -->
[Learn how to contact support](/user-guides/contact-support)

<!-- Proper heading hierarchy -->
# Page Title
## Main Section
### Subsection
```

## Resources

* [WCAG 2.1 AA Guidelines](https://www.w3.org/WAI/WCAG21/quickref/?levels=aa)
* [EU Accessibility Act Overview](https://commission.europa.eu/strategy-and-policy/policies/justice-and-fundamental-rights/disability/union-equality-strategy-rights-persons-disabilities-2021-2030/european-accessibility-act_en)
* [WebAIM Accessibility Resources](https://webaim.org/)
* [MDN Accessibility Guidelines](https://developer.mozilla.org/en-US/docs/Web/Accessibility)

***

<Check>
  **Implementation Note**: These templates should be used as the standard for all new documentation and when updating existing pages. Consistency across all 96+ MDX files ensures compliance and better user experience.
</Check>