claude-plugin-wordpress-manager 1.4.0 → 1.7.0

package/skills/wp-accessibility/references/interactive-a11y.md

@@ -0,0 +1,272 @@
+# Interactive Component Accessibility
+
+Use this file when building accessible interactive components (modals, tabs, accordions, tooltips) in WordPress.
+
+## Modal / Dialog
+
+Based on [ARIA Authoring Practices Guide (APG) Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/).
+
+```html
+<div role="dialog" aria-modal="true"
+     aria-labelledby="dialog-title"
+     aria-describedby="dialog-desc">
+    <h2 id="dialog-title">Confirm Action</h2>
+    <p id="dialog-desc">Are you sure you want to proceed?</p>
+    <button>Confirm</button>
+    <button>Cancel</button>
+</div>
+```
+
+### Keyboard behavior
+
+| Key | Action |
+|-----|--------|
+| Tab | Move focus to next focusable element inside dialog |
+| Shift+Tab | Move focus to previous focusable element |
+| Escape | Close dialog |
+
+### Focus management
+
+```js
+class AccessibleModal {
+    open(trigger) {
+        this.trigger = trigger;
+        this.dialog.hidden = false;
+        this.dialog.setAttribute('aria-modal', 'true');
+
+        // Trap focus inside dialog
+        this.firstFocusable = this.dialog.querySelector(
+            'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+        );
+        this.firstFocusable?.focus();
+
+        // Prevent background scroll
+        document.body.style.overflow = 'hidden';
+    }
+
+    close() {
+        this.dialog.hidden = true;
+        document.body.style.overflow = '';
+
+        // Return focus to trigger element
+        this.trigger?.focus();
+    }
+
+    trapFocus(e) {
+        if (e.key !== 'Tab') return;
+        const focusable = this.dialog.querySelectorAll(
+            'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+        );
+        const first = focusable[0];
+        const last = focusable[focusable.length - 1];
+
+        if (e.shiftKey && document.activeElement === first) {
+            e.preventDefault();
+            last.focus();
+        } else if (!e.shiftKey && document.activeElement === last) {
+            e.preventDefault();
+            first.focus();
+        }
+    }
+}
+```
+
+## Tabs
+
+Based on [APG Tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/).
+
+```html
+<div class="tabs">
+    <div role="tablist" aria-label="Settings">
+        <button role="tab" id="tab-1" aria-selected="true"
+                aria-controls="panel-1" tabindex="0">
+            General
+        </button>
+        <button role="tab" id="tab-2" aria-selected="false"
+                aria-controls="panel-2" tabindex="-1">
+            Advanced
+        </button>
+    </div>
+    <div role="tabpanel" id="panel-1" aria-labelledby="tab-1" tabindex="0">
+        General settings content
+    </div>
+    <div role="tabpanel" id="panel-2" aria-labelledby="tab-2" tabindex="0"
+         hidden>
+        Advanced settings content
+    </div>
+</div>
+```
+
+### Keyboard behavior
+
+| Key | Action |
+|-----|--------|
+| Arrow Right | Activate next tab |
+| Arrow Left | Activate previous tab |
+| Home | Activate first tab |
+| End | Activate last tab |
+| Tab | Move focus into the active tab panel |
+
+```js
+tablist.addEventListener('keydown', (e) => {
+    const tabs = [...tablist.querySelectorAll('[role="tab"]')];
+    const index = tabs.indexOf(document.activeElement);
+
+    let newIndex;
+    switch (e.key) {
+        case 'ArrowRight':
+            newIndex = (index + 1) % tabs.length;
+            break;
+        case 'ArrowLeft':
+            newIndex = (index - 1 + tabs.length) % tabs.length;
+            break;
+        case 'Home':
+            newIndex = 0;
+            break;
+        case 'End':
+            newIndex = tabs.length - 1;
+            break;
+        default:
+            return;
+    }
+    e.preventDefault();
+    activateTab(tabs[newIndex]);
+});
+
+function activateTab(tab) {
+    // Deactivate all
+    tablist.querySelectorAll('[role="tab"]').forEach((t) => {
+        t.setAttribute('aria-selected', 'false');
+        t.setAttribute('tabindex', '-1');
+        document.getElementById(t.getAttribute('aria-controls')).hidden = true;
+    });
+    // Activate selected
+    tab.setAttribute('aria-selected', 'true');
+    tab.setAttribute('tabindex', '0');
+    tab.focus();
+    document.getElementById(tab.getAttribute('aria-controls')).hidden = false;
+}
+```
+
+## Accordion
+
+Based on [APG Accordion pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/).
+
+```html
+<div class="accordion">
+    <h3>
+        <button aria-expanded="true" aria-controls="sect1"
+                id="accordion1-header">
+            Section 1
+        </button>
+    </h3>
+    <div id="sect1" role="region" aria-labelledby="accordion1-header">
+        <p>Section 1 content</p>
+    </div>
+
+    <h3>
+        <button aria-expanded="false" aria-controls="sect2"
+                id="accordion2-header">
+            Section 2
+        </button>
+    </h3>
+    <div id="sect2" role="region" aria-labelledby="accordion2-header"
+         hidden>
+        <p>Section 2 content</p>
+    </div>
+</div>
+```
+
+### Keyboard behavior
+
+| Key | Action |
+|-----|--------|
+| Enter / Space | Toggle section |
+| Arrow Down | Next header |
+| Arrow Up | Previous header |
+| Home | First header |
+| End | Last header |
+
+## Tooltip
+
+```html
+<button aria-describedby="tooltip-1">
+    Settings
+</button>
+<div role="tooltip" id="tooltip-1" class="tooltip" hidden>
+    Configure application settings
+</div>
+```
+
+### Behavior
+
+- Show on hover and focus
+- Hide on Escape
+- Do not use for essential information (tooltips are supplementary)
+- Keep content brief (one sentence max)
+
+```js
+const trigger = document.querySelector('[aria-describedby]');
+const tooltip = document.getElementById('tooltip-1');
+
+trigger.addEventListener('mouseenter', () => tooltip.hidden = false);
+trigger.addEventListener('mouseleave', () => tooltip.hidden = true);
+trigger.addEventListener('focus', () => tooltip.hidden = false);
+trigger.addEventListener('blur', () => tooltip.hidden = true);
+trigger.addEventListener('keydown', (e) => {
+    if (e.key === 'Escape') tooltip.hidden = true;
+});
+```
+
+## Disclosure (show/hide)
+
+```html
+<button aria-expanded="false" aria-controls="details-content">
+    Show Details
+</button>
+<div id="details-content" hidden>
+    <p>Additional details here.</p>
+</div>
+```
+
+```js
+button.addEventListener('click', () => {
+    const expanded = button.getAttribute('aria-expanded') === 'true';
+    button.setAttribute('aria-expanded', String(!expanded));
+    content.hidden = expanded;
+    button.textContent = expanded ? 'Show Details' : 'Hide Details';
+});
+```
+
+## WordPress @wordpress/components
+
+WordPress core components are pre-built with accessibility:
+
+```js
+import { Modal, TabPanel, Notice } from '@wordpress/components';
+
+// Modal — handles focus trap, Escape, aria-modal automatically
+<Modal title="Settings" onRequestClose={closeModal}>
+    <p>Modal content</p>
+</Modal>
+
+// TabPanel — handles arrow keys, aria-selected automatically
+<TabPanel
+    tabs={[
+        { name: 'general', title: 'General' },
+        { name: 'advanced', title: 'Advanced' },
+    ]}
+>
+    {(tab) => <p>{tab.name} content</p>}
+</TabPanel>
+```
+
+Prefer `@wordpress/components` over custom implementations when building for the block editor.
+
+## Verification
+
+1. Keyboard-only navigation: can you operate the component without a mouse?
+2. Screen reader: does it announce state changes (expanded/collapsed, selected tab)?
+3. Focus management: does focus move to the right place on open/close?
+4. Escape key: does it close overlays and tooltips?
+5. No focus traps: can you escape from every component?

package/skills/wp-accessibility/references/media-a11y.md

@@ -0,0 +1,254 @@
+# Media Accessibility
+
+Use this file when making images, video, audio, and embedded media accessible in WordPress.
+
+## Images
+
+### Alt text decision tree
+
+1. **Is the image decorative?** → `alt=""`
+2. **Does it contain text?** → alt = the text in the image
+3. **Is it a link/button?** → alt = the link destination or action
+4. **Does it convey information?** → alt = describe the information
+5. **Is it complex (chart/graph)?** → alt = brief summary + detailed description nearby
+
+### WordPress implementation
+
+```php
+// Featured image with alt text
+if (has_post_thumbnail()) {
+    $alt = get_post_meta(
+        get_post_thumbnail_id(), '_wp_attachment_image_alt', true
+    );
+    the_post_thumbnail('large', ['alt' => $alt ?: get_the_title()]);
+}
+
+// Custom image output
+$image_id = get_field('hero_image'); // ACF example
+$alt = get_post_meta($image_id, '_wp_attachment_image_alt', true);
+echo wp_get_attachment_image($image_id, 'full', false, [
+    'alt' => $alt,
+    'loading' => 'lazy',
+]);
+```
+
+### Decorative images
+
+```html
+<!-- Decorative: empty alt, presentational role -->
+<img src="divider.svg" alt="" role="presentation">
+
+<!-- CSS background for purely decorative -->
+<div class="decorative-bg" aria-hidden="true"></div>
+```
+
+### Complex images
+
+```html
+<figure>
+    <img src="chart.png"
+         alt="Q4 revenue chart showing 25% growth"
+         aria-describedby="chart-details">
+    <figcaption id="chart-details">
+        Revenue grew from $2M in Q3 to $2.5M in Q4, driven primarily
+        by the European market which accounted for 60% of new sales.
+    </figcaption>
+</figure>
+```
+
+### SVG accessibility
+
+```html
+<!-- Informative SVG -->
+<svg role="img" aria-labelledby="svg-title svg-desc">
+    <title id="svg-title">Company Logo</title>
+    <desc id="svg-desc">Green shield with leaf motif</desc>
+    <!-- svg paths -->
+</svg>
+
+<!-- Decorative SVG -->
+<svg aria-hidden="true" focusable="false">
+    <!-- svg paths -->
+</svg>
+```
+
+## Video
+
+### WordPress video block
+
+The core Video block supports:
+- Captions (`.vtt` files)
+- Poster image (alt text via the poster)
+- Playback controls (native browser controls are accessible)
+
+### Captions and subtitles
+
+```html
+<video controls>
+    <source src="video.mp4" type="video/mp4">
+    <track kind="captions" src="captions-en.vtt"
+           srclang="en" label="English" default>
+    <track kind="captions" src="captions-it.vtt"
+           srclang="it" label="Italiano">
+    <track kind="descriptions" src="descriptions-en.vtt"
+           srclang="en" label="English audio descriptions">
+</video>
+```
+
+### WebVTT format
+
+```vtt
+WEBVTT
+
+00:00:01.000 --> 00:00:04.000
+Welcome to our product demonstration.
+
+00:00:04.500 --> 00:00:08.000
+Today we'll show you the key features
+of our new application.
+
+00:00:08.500 --> 00:00:12.000
+[Music playing in background]
+```
+
+### WCAG video requirements
+
+| Level | Requirement |
+|-------|------------|
+| A | Captions for prerecorded video |
+| A | Audio description or media alternative for prerecorded video |
+| AA | Captions for live video |
+| AA | Audio descriptions for prerecorded video |
+| AAA | Sign language interpretation |
+| AAA | Extended audio descriptions |
+
+### Autoplay restrictions
+
+```html
+<!-- NEVER autoplay with sound -->
+<video autoplay muted playsinline>
+    <!-- Muted autoplay is acceptable for decorative/background video -->
+</video>
+
+<!-- Provide pause control for autoplay -->
+<div class="video-wrapper">
+    <video autoplay muted loop id="bg-video">
+        <source src="bg.mp4" type="video/mp4">
+    </video>
+    <button aria-label="Pause background video"
+            onclick="toggleVideo()">
+        Pause
+    </button>
+</div>
+```
+
+## Audio
+
+```html
+<audio controls>
+    <source src="podcast.mp3" type="audio/mpeg">
+    <a href="podcast.mp3">Download podcast episode</a>
+</audio>
+
+<!-- Provide transcript for audio content -->
+<details>
+    <summary>Read transcript</summary>
+    <div class="transcript">
+        <p><strong>Host:</strong> Welcome to the show...</p>
+    </div>
+</details>
+```
+
+### WCAG audio requirements
+
+| Level | Requirement |
+|-------|------------|
+| A | Transcript for prerecorded audio-only content |
+| AAA | Sign language for prerecorded audio in video |
+
+## Embedded media (iframes)
+
+```html
+<!-- YouTube/Vimeo embeds need titles -->
+<iframe src="https://www.youtube.com/embed/VIDEO_ID"
+        title="Product demonstration video"
+        allowfullscreen>
+</iframe>
+
+<!-- Maps -->
+<iframe src="https://www.google.com/maps/embed?..."
+        title="Store location map - 123 Main Street, Rome"
+        allowfullscreen>
+</iframe>
+```
+
+### WordPress oEmbed
+
+WordPress auto-embeds URLs. Add accessible wrappers:
+
+```php
+add_filter('embed_oembed_html', function($html, $url, $attr) {
+    // Add responsive wrapper with accessible title
+    return sprintf(
+        '<div class="responsive-embed" role="group" aria-label="%s">%s</div>',
+        esc_attr__('Embedded media', 'my-theme'),
+        $html
+    );
+}, 10, 3);
+```
+
+## Animations and motion
+
+```css
+/* Respect prefers-reduced-motion */
+@media (prefers-reduced-motion: reduce) {
+    *,
+    *::before,
+    *::after {
+        animation-duration: 0.01ms !important;
+        animation-iteration-count: 1 !important;
+        transition-duration: 0.01ms !important;
+        scroll-behavior: auto !important;
+    }
+
+    video, .animated-element {
+        animation: none !important;
+    }
+}
+```
+
+```js
+// Check user preference in JavaScript
+const prefersReducedMotion = window.matchMedia(
+    '(prefers-reduced-motion: reduce)'
+).matches;
+
+if (!prefersReducedMotion) {
+    // Run animations
+}
+```
+
+WCAG requirements:
+- Content that moves, blinks, or scrolls for more than 5 seconds must have a pause mechanism
+- No content flashes more than 3 times per second
+
+## Verification
+
+```bash
+# Check for images without alt text
+curl -s https://site.com/ | grep -oP '<img[^>]*>' | grep -v 'alt='
+
+# Check for iframes without titles
+curl -s https://site.com/ | grep -oP '<iframe[^>]*>' | grep -v 'title='
+
+# Check for video without captions
+curl -s https://site.com/ | grep -oP '<video[^>]*>.*?</video>' | grep -v '<track'
+```
+
+Manual checks:
+1. All informative images have descriptive alt text
+2. Decorative images have `alt=""`
+3. Videos have captions
+4. Audio has transcripts
+5. No autoplay media with sound
+6. Animations respect `prefers-reduced-motion`