novahiz 0.1.0

package/bundled-skills/a11y-audit/expected_outputs/sample-scan-report.md

@@ -0,0 +1,63 @@
+# A11y Audit Report — sample-component.tsx
+
+**Scanned:** 1 file | **Issues:** 9 | **Status:** FAIL
+
+## Critical (3)
+
+### 1. Missing alt text on image
+- **File:** sample-component.tsx:7
+- **Code:** `<img src={user.avatar} />`
+- **WCAG:** 1.1.1 Non-text Content (Level A)
+- **Fix:** Add descriptive alt text: `<img src={user.avatar} alt={`${user.name}'s avatar`} />`
+
+### 2. Click handler without keyboard support
+- **File:** sample-component.tsx:5
+- **Code:** `<div className="card" onClick={() => onEdit(user.id)}>`
+- **WCAG:** 2.1.1 Keyboard (Level A)
+- **Fix:** Use `<button>` or add `role="button"`, `tabIndex={0}`, and `onKeyDown`
+
+### 3. Click handler without keyboard support
+- **File:** sample-component.tsx:11
+- **Code:** `<div onClick={() => onDelete(user.id)} ...>`
+- **WCAG:** 2.1.1 Keyboard (Level A)
+- **Fix:** Replace `<div>` with `<button>`
+
+## Serious (4)
+
+### 4. Missing form label
+- **File:** sample-component.tsx:15
+- **Code:** `<input placeholder="Add note" />`
+- **WCAG:** 3.3.2 Labels or Instructions (Level A)
+- **Fix:** Add `<label>` or `aria-label="Add note"`
+
+### 5. Empty link
+- **File:** sample-component.tsx:14
+- **Code:** `<a href="#">Edit</a>`
+- **WCAG:** 2.4.4 Link Purpose (Level A)
+- **Fix:** Use a real href or replace with `<button>`
+
+### 6. tabindex greater than 0
+- **File:** sample-component.tsx:24
+- **Code:** `tabIndex={5}`
+- **WCAG:** 2.4.3 Focus Order (Level A)
+- **Fix:** Use `tabIndex={0}` — positive values disrupt natural tab order
+
+### 7. Missing table headers
+- **File:** sample-component.tsx:30
+- **Code:** `<td><b>Name</b></td>` (using td+b instead of th)
+- **WCAG:** 1.3.1 Info and Relationships (Level A)
+- **Fix:** Use `<th scope="col">Name</th>`
+
+## Moderate (2)
+
+### 8. Missing form label
+- **File:** sample-component.tsx:22
+- **Code:** `<input type="text" placeholder="Search..." />`
+- **WCAG:** 3.3.2 Labels or Instructions (Level A)
+- **Fix:** Add `aria-label="Search"` or visible label
+
+### 9. Color as sole indicator
+- **File:** sample-component.tsx:38
+- **Code:** `style={{ color: row.active ? 'green' : 'red' }}`
+- **WCAG:** 1.4.1 Use of Color (Level A)
+- **Fix:** Add text or icon alongside color: `{row.active ? '✓ Active' : '✗ Inactive'}`

package/bundled-skills/a11y-audit/references/aria-patterns.md

@@ -0,0 +1,223 @@
+# ARIA Patterns & Keyboard Interaction Reference
+
+## Landmark Roles
+
+Every page should have these landmarks:
+
+```html
+<header role="banner">         <!-- Site header — once per page -->
+<nav role="navigation">         <!-- Navigation — can have multiple with aria-label -->
+<main role="main">              <!-- Main content — once per page -->
+<aside role="complementary">    <!-- Sidebar — related but not essential -->
+<footer role="contentinfo">     <!-- Site footer — once per page -->
+<form role="search">            <!-- Search form -->
+```
+
+**Semantic HTML equivalents:** `<header>`, `<nav>`, `<main>`, `<aside>`, `<footer>` provide implicit roles — no need to double up with explicit `role` attributes.
+
+## Live Regions
+
+### When to Use
+
+| Pattern | Attribute | Use Case |
+|---------|-----------|----------|
+| Polite | `aria-live="polite"` | Toast notifications, status updates, search result counts |
+| Assertive | `aria-live="assertive"` | Error messages, urgent alerts, form validation errors |
+| Status | `role="status"` | Loading indicators, progress updates |
+| Alert | `role="alert"` | Error dialogs, time-sensitive warnings |
+| Log | `role="log"` | Chat messages, activity feeds |
+| Timer | `role="timer"` | Countdown timers |
+
+### Implementation
+
+```html
+<!-- Toast notifications -->
+<div aria-live="polite" aria-atomic="true">
+  <!-- Inject toast content here dynamically -->
+</div>
+
+<!-- Form validation errors -->
+<div aria-live="assertive" role="alert">
+  <p>Please enter a valid email address.</p>
+</div>
+
+<!-- Loading state -->
+<div role="status" aria-live="polite">
+  Loading results...
+</div>
+```
+
+**Key rule:** The live region container must exist in the DOM *before* content is injected. Adding `aria-live` to a newly created element won't announce it.
+
+## Focus Management
+
+### Focus Trap (Modals)
+
+```javascript
+// Trap focus inside modal
+const modal = document.querySelector('[role="dialog"]');
+const focusable = modal.querySelectorAll(
+  'a[href], button, textarea, input, select, [tabindex]:not([tabindex="-1"])'
+);
+const first = focusable[0];
+const last = focusable[focusable.length - 1];
+
+modal.addEventListener('keydown', (e) => {
+  if (e.key === 'Tab') {
+    if (e.shiftKey && document.activeElement === first) {
+      e.preventDefault();
+      last.focus();
+    } else if (!e.shiftKey && document.activeElement === last) {
+      e.preventDefault();
+      first.focus();
+    }
+  }
+  if (e.key === 'Escape') closeModal();
+});
+```
+
+### Focus Restoration
+
+```javascript
+// Save focus before opening modal
+const trigger = document.activeElement;
+openModal();
+
+// Restore focus on close
+function closeModal() {
+  modal.hidden = true;
+  trigger.focus();
+}
+```
+
+### Skip Link
+
+```html
+<a href="#main-content" class="skip-link">Skip to main content</a>
+<!-- ... navigation ... -->
+<main id="main-content" tabindex="-1">
+```
+
+```css
+.skip-link {
+  position: absolute;
+  left: -9999px;
+  z-index: 999;
+}
+.skip-link:focus {
+  left: 10px;
+  top: 10px;
+  background: #000;
+  color: #fff;
+  padding: 8px 16px;
+}
+```
+
+## Keyboard Interaction Patterns
+
+### Tabs
+
+```
+Tab          → Move to tab list, then to tab panel
+Arrow Left/Right → Switch between tabs
+Home         → First tab
+End          → Last tab
+```
+
+```html
+<div role="tablist" aria-label="Settings">
+  <button role="tab" aria-selected="true" aria-controls="panel-1" id="tab-1">General</button>
+  <button role="tab" aria-selected="false" aria-controls="panel-2" id="tab-2" tabindex="-1">Security</button>
+</div>
+<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">...</div>
+<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>...</div>
+```
+
+### Combobox / Autocomplete
+
+```
+Arrow Down   → Open list / next option
+Arrow Up     → Previous option
+Enter        → Select option
+Escape       → Close list
+Type         → Filter options
+```
+
+### Menu
+
+```
+Enter/Space  → Activate item
+Arrow Down   → Next item
+Arrow Up     → Previous item
+Arrow Right  → Open submenu
+Arrow Left   → Close submenu
+Escape       → Close menu
+```
+
+### Accordion
+
+```
+Enter/Space  → Toggle section
+Arrow Down   → Next header
+Arrow Up     → Previous header
+Home         → First header
+End          → Last header
+```
+
+## Framework-Specific ARIA
+
+### React
+
+```jsx
+// Announce route changes (SPA)
+<div aria-live="polite" className="sr-only">
+  {`Navigated to ${pageTitle}`}
+</div>
+
+// Error boundary with accessible error
+<div role="alert">
+  <h2>Something went wrong</h2>
+  <p>{error.message}</p>
+</div>
+```
+
+### Vue
+
+```vue
+<!-- Announce dynamic content -->
+<div aria-live="polite">
+  <p v-if="results.length">{{ results.length }} results found</p>
+</div>
+
+<!-- Accessible toggle -->
+<button
+  :aria-expanded="isOpen"
+  :aria-controls="panelId"
+  @click="toggle"
+>
+  {{ isOpen ? 'Collapse' : 'Expand' }}
+</button>
+```
+
+### Angular
+
+```html
+<!-- cdkTrapFocus for modals -->
+<div cdkTrapFocus cdkTrapFocusAutoCapture role="dialog" aria-labelledby="dialog-title">
+  <h2 id="dialog-title">Confirm Action</h2>
+</div>
+
+<!-- LiveAnnouncer service -->
+<!-- In component: this.liveAnnouncer.announce('Item added to cart'); -->
+```
+
+## Common ARIA Mistakes
+
+| Mistake | Why It's Wrong | Fix |
+|---------|---------------|-----|
+| `<div role="button">` without keyboard | Div doesn't get keyboard events | Use `<button>` or add `tabindex="0"` + `onkeydown` |
+| `aria-hidden="true"` on focusable element | Screen reader skips it but keyboard reaches it | Remove from tab order too: `tabindex="-1"` |
+| `aria-label` overriding visible text | Confusing for sighted screen reader users | Use `aria-labelledby` pointing to visible text |
+| Redundant ARIA on semantic HTML | `<nav role="navigation">` is redundant | Drop the `role` — `<nav>` implies it |
+| `aria-live` on container that already has content | Initial content gets announced on load | Add `aria-live` to empty container, inject content after |
+| Missing `aria-expanded` on toggles | Screen reader can't tell if section is open | Add `aria-expanded="true/false"` |

package/bundled-skills/a11y-audit/references/audit-report-template.md

@@ -0,0 +1,46 @@
+# Audit Report Template
+
+The scanner generates a stakeholder-ready report when run with the `--report` flag:
+
+```bash
+python scripts/a11y_scanner.py /path/to/project --report --output audit-report.md
+```
+
+## Generated Report Structure
+
+```markdown
+# Accessibility Audit Report
+**Project:** Acme Dashboard
+**Date:** 2026-03-18
+**Standard:** WCAG 2.2 Level AA
+**Tool:** a11y-audit v2.1.2
+
+## Executive Summary
+- Files Scanned: 127
+- Total Violations: 14
+- Critical: 3 | Major: 7 | Minor: 4
+- Estimated Remediation: 8-12 hours
+- Compliance Score: 72% (Target: 100%)
+
+## Violations by Category
+| Category | Count | Severity Breakdown |
+|----------|-------|--------------------|
+| Missing Alt Text | 3 | 2 Critical, 1 Minor |
+| Keyboard Access | 4 | 2 Critical, 2 Major |
+| Color Contrast | 3 | 3 Major |
+| Form Labels | 2 | 2 Major |
+| ARIA Usage | 2 | 2 Minor |
+
+## Detailed Findings
+[Per-violation details with file, line, WCAG criterion, and fix]
+
+## Remediation Priority
+1. Fix all Critical issues (blocks release)
+2. Fix Major issues in current sprint
+3. Schedule Minor issues for next sprint
+
+## Recommendations
+- Add a11y linting to CI pipeline (eslint-plugin-jsx-a11y)
+- Include keyboard testing in QA checklist
+- Schedule quarterly manual audit with assistive technology
+```

package/bundled-skills/a11y-audit/references/ci-cd-integration.md

@@ -0,0 +1,127 @@
+# CI/CD Integration for Accessibility Auditing
+
+## GitHub Actions
+
+```yaml
+# .github/workflows/a11y-audit.yml
+name: Accessibility Audit
+
+on:
+  pull_request:
+    paths:
+      - 'src/**/*.tsx'
+      - 'src/**/*.vue'
+      - 'src/**/*.html'
+      - 'src/**/*.svelte'
+
+jobs:
+  a11y-audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Run A11y Scanner
+        run: |
+          python scripts/a11y_scanner.py ./src --json > a11y-results.json
+
+      - name: Check for Critical Issues
+        run: |
+          python -c "
+          import json, sys
+          with open('a11y-results.json') as f:
+              data = json.load(f)
+          critical = [v for v in data.get('violations', []) if v['severity'] == 'critical']
+          if critical:
+              print(f'FAILED: {len(critical)} critical a11y violations found')
+              for v in critical:
+                  print(f\"  [{v['wcag']}] {v['file']}:{v['line']} - {v['message']}\")
+              sys.exit(1)
+          print('PASSED: No critical a11y violations')
+          "
+
+      - name: Upload Audit Report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: a11y-audit-report
+          path: a11y-results.json
+
+      - name: Comment on PR
+        if: failure()
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: a11y-audit
+          message: |
+            ## Accessibility Audit Failed
+            Critical WCAG 2.2 violations were found. See the uploaded artifact for details.
+            Run `python scripts/a11y_scanner.py ./src` locally to view and fix issues.
+```
+
+## GitLab CI
+
+```yaml
+# .gitlab-ci.yml
+a11y-audit:
+  stage: test
+  image: python:3.11-slim
+  script:
+    - python scripts/a11y_scanner.py ./src --json > a11y-results.json
+    - python -c "
+      import json, sys;
+      data = json.load(open('a11y-results.json'));
+      critical = [v for v in data.get('violations', []) if v['severity'] == 'critical'];
+      sys.exit(1) if critical else print('A11y audit passed')
+      "
+  artifacts:
+    paths:
+      - a11y-results.json
+    when: always
+  rules:
+    - changes:
+        - "src/**/*.{tsx,vue,html,svelte}"
+```
+
+## Azure DevOps
+
+```yaml
+# azure-pipelines.yml
+- task: PythonScript@0
+  displayName: 'Run A11y Audit'
+  inputs:
+    scriptSource: 'filePath'
+    scriptPath: 'scripts/a11y_scanner.py'
+    arguments: './src --json --output $(Build.ArtifactStagingDirectory)/a11y-results.json'
+
+- task: PublishBuildArtifacts@1
+  condition: always()
+  inputs:
+    PathtoPublish: '$(Build.ArtifactStagingDirectory)/a11y-results.json'
+    ArtifactName: 'a11y-audit-report'
+```
+
+## Pre-Commit Hook
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+
+# Run a11y scan on staged files only
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(tsx|vue|html|svelte|jsx)$')
+
+if [ -n "$STAGED_FILES" ]; then
+  echo "Running accessibility audit on staged files..."
+  for file in $STAGED_FILES; do
+    python scripts/a11y_scanner.py "$file" --severity critical --quiet
+    if [ $? -ne 0 ]; then
+      echo "A11y audit FAILED for $file. Fix critical issues before committing."
+      exit 1
+    fi
+  done
+  echo "A11y audit passed."
+fi
+```

package/bundled-skills/a11y-audit/references/color-contrast-guide.md

@@ -0,0 +1,83 @@
+# Color Contrast Guide
+
+## Contrast Checker Usage
+
+The `contrast_checker.py` script validates color pairs against WCAG 2.2 contrast requirements.
+
+```bash
+# Check a single color pair
+python scripts/contrast_checker.py --fg "#777777" --bg "#ffffff"
+
+# Output:
+# Foreground: #777777 | Background: #ffffff
+# Contrast Ratio: 4.48:1
+# AA Normal Text (4.5:1): FAIL
+# AA Large Text (3.0:1):  PASS
+# AAA Normal Text (7.0:1): FAIL
+# Suggested alternative: #767676 (4.54:1 - passes AA)
+
+# Scan a CSS file for all color pairs
+python scripts/contrast_checker.py --file src/styles/globals.css
+
+# Scan Tailwind classes in components
+python scripts/contrast_checker.py --tailwind src/components/
+```
+
+## Common Contrast Fixes
+
+| Original Color | Contrast on White | Fix | New Contrast |
+|----------------|------------------|-----|--------------|
+| `#aaaaaa` | 2.32:1 | `#767676` | 4.54:1 (AA) |
+| `#999999` | 2.85:1 | `#767676` | 4.54:1 (AA) |
+| `#888888` | 3.54:1 | `#767676` | 4.54:1 (AA) |
+| `#777777` | 4.48:1 | `#757575` | 4.60:1 (AA) |
+| `#66bb6a` | 3.06:1 | `#2e7d32` | 5.87:1 (AA) |
+| `#42a5f5` | 2.81:1 | `#1565c0` | 6.08:1 (AA) |
+| `#ef5350` | 3.13:1 | `#c62828` | 5.57:1 (AA) |
+
+## Tailwind CSS Accessible Palette Mapping
+
+| Inaccessible Class | Contrast on White | Accessible Alternative | Contrast |
+|---------------------|------------------|----------------------|----------|
+| `text-gray-400` | 2.68:1 | `text-gray-600` | 5.74:1 |
+| `text-blue-400` | 2.81:1 | `text-blue-700` | 5.96:1 |
+| `text-green-400` | 2.12:1 | `text-green-700` | 5.18:1 |
+| `text-red-400` | 3.04:1 | `text-red-700` | 6.05:1 |
+| `text-yellow-500` | 1.47:1 | `text-yellow-800` | 7.34:1 |
+
+## Screen Reader Utility Class
+
+Every project should include this utility class for visually hiding content while keeping it accessible to screen readers:
+
+```css
+/* Visually hidden but accessible to screen readers */
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border-width: 0;
+}
+
+/* Allow the element to be focusable when navigated to via keyboard */
+.sr-only-focusable:focus,
+.sr-only-focusable:active {
+  position: static;
+  width: auto;
+  height: auto;
+  padding: inherit;
+  margin: inherit;
+  overflow: visible;
+  clip: auto;
+  white-space: inherit;
+}
+```
+
+Tailwind CSS includes this as `sr-only` by default. For other frameworks:
+- **Angular**: Add to `styles.scss`
+- **Vue**: Add to `assets/global.css`
+- **Svelte**: Add to `app.css`