@diottodev/runic 1.0.0 → 1.1.0

package/engineering-team/a11y-audit/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/engineering-team/a11y-audit/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`

package/engineering-team/a11y-audit/skills/a11y-audit/references/examples-by-framework.md

@@ -0,0 +1,312 @@
+# Accessibility Audit Examples by Framework
+
+## Example 1: Vue SFC Form Audit
+
+```vue
+<!-- BEFORE: src/components/LoginForm.vue -->
+<template>
+  <form @submit="handleLogin">
+    <input type="text" placeholder="Email" v-model="email" />
+    <input type="password" placeholder="Password" v-model="password" />
+    <div v-if="error" style="color: red">{{ error }}</div>
+    <div @click="handleLogin">Sign In</div>
+  </form>
+</template>
+```
+
+**Violations detected:**
+
+| # | WCAG | Severity | Issue |
+|---|------|----------|-------|
+| 1 | 1.3.1 | Critical | Inputs missing associated `<label>` elements |
+| 2 | 3.3.2 | Major | Placeholder text used as only label (disappears on input) |
+| 3 | 2.1.1 | Critical | `<div @click>` not keyboard accessible |
+| 4 | 4.1.3 | Major | Error message not announced to screen readers |
+| 5 | 3.3.1 | Major | Error not programmatically associated with input |
+
+```vue
+<!-- AFTER: src/components/LoginForm.vue -->
+<template>
+  <form @submit.prevent="handleLogin" aria-label="Sign in to your account">
+    <div class="field">
+      <label for="login-email">Email</label>
+      <input
+        id="login-email"
+        type="email"
+        v-model="email"
+        autocomplete="email"
+        required
+        :aria-describedby="emailError ? 'email-error' : undefined"
+        :aria-invalid="!!emailError"
+      />
+      <span v-if="emailError" id="email-error" role="alert">
+        {{ emailError }}
+      </span>
+    </div>
+    <div class="field">
+      <label for="login-password">Password</label>
+      <input
+        id="login-password"
+        type="password"
+        v-model="password"
+        autocomplete="current-password"
+        required
+        :aria-describedby="passwordError ? 'password-error' : undefined"
+        :aria-invalid="!!passwordError"
+      />
+      <span v-if="passwordError" id="password-error" role="alert">
+        {{ passwordError }}
+      </span>
+    </div>
+    <div v-if="error" role="alert" aria-live="assertive" class="form-error">
+      {{ error }}
+    </div>
+    <button type="submit">Sign In</button>
+  </form>
+</template>
+```
+
+## Example 2: Angular Template Audit
+
+```html
+<!-- BEFORE: src/app/dashboard/dashboard.component.html -->
+<div class="tabs">
+  <div *ngFor="let tab of tabs"
+       (click)="selectTab(tab)"
+       [class.active]="tab.active">
+    {{ tab.label }}
+  </div>
+</div>
+<div class="tab-content">
+  <div *ngIf="selectedTab">{{ selectedTab.content }}</div>
+</div>
+```
+
+**Violations detected:**
+
+| # | WCAG | Severity | Issue |
+|---|------|----------|-------|
+| 1 | 4.1.2 | Critical | Tab widget missing ARIA roles (`tablist`, `tab`, `tabpanel`) |
+| 2 | 2.1.1 | Critical | Tabs not keyboard navigable (arrow keys, Home, End) |
+| 3 | 2.4.11 | Major | No visible focus indicator on active tab |
+
+```html
+<!-- AFTER: src/app/dashboard/dashboard.component.html -->
+<div class="tabs" role="tablist" aria-label="Dashboard sections">
+  <button
+    *ngFor="let tab of tabs; let i = index"
+    role="tab"
+    [id]="'tab-' + tab.id"
+    [attr.aria-selected]="tab.active"
+    [attr.aria-controls]="'panel-' + tab.id"
+    [attr.tabindex]="tab.active ? 0 : -1"
+    (click)="selectTab(tab)"
+    (keydown)="handleTabKeydown($event, i)"
+    class="tab-button"
+    [class.active]="tab.active">
+    {{ tab.label }}
+  </button>
+</div>
+<div
+  *ngIf="selectedTab"
+  role="tabpanel"
+  [id]="'panel-' + selectedTab.id"
+  [attr.aria-labelledby]="'tab-' + selectedTab.id"
+  tabindex="0"
+  class="tab-content">
+  {{ selectedTab.content }}
+</div>
+```
+
+**Supporting TypeScript for keyboard navigation:**
+
+```typescript
+// dashboard.component.ts
+handleTabKeydown(event: KeyboardEvent, index: number): void {
+  const tabCount = this.tabs.length;
+  let newIndex = index;
+
+  switch (event.key) {
+    case 'ArrowRight':
+      newIndex = (index + 1) % tabCount;
+      break;
+    case 'ArrowLeft':
+      newIndex = (index - 1 + tabCount) % tabCount;
+      break;
+    case 'Home':
+      newIndex = 0;
+      break;
+    case 'End':
+      newIndex = tabCount - 1;
+      break;
+    default:
+      return;
+  }
+
+  event.preventDefault();
+  this.selectTab(this.tabs[newIndex]);
+  // Move focus to the new tab button
+  const tabElement = document.getElementById(`tab-${this.tabs[newIndex].id}`);
+  tabElement?.focus();
+}
+```
+
+## Example 3: Next.js Page-Level Audit
+
+```tsx
+// BEFORE: src/app/page.tsx
+export default function Home() {
+  return (
+    <main>
+      <div className="text-4xl font-bold">Welcome to Acme</div>
+      <div className="mt-4">
+        Build better products with our platform.
+      </div>
+      <div className="mt-8 bg-blue-600 text-white px-6 py-3 rounded cursor-pointer"
+           onClick={() => router.push('/signup')}>
+        Get Started
+      </div>
+    </main>
+  );
+}
+```
+
+**Violations detected:**
+
+| # | WCAG | Severity | Issue |
+|---|------|----------|-------|
+| 1 | 1.3.1 | Major | Heading uses `<div>` instead of `<h1>` -- no semantic structure |
+| 2 | 2.4.2 | Major | Page missing `<title>` (Next.js metadata) |
+| 3 | 2.1.1 | Critical | CTA uses `<div onClick>` -- not keyboard accessible |
+| 4 | 3.1.1 | Minor | `<html>` missing `lang` attribute (check `layout.tsx`) |
+
+```tsx
+// AFTER: src/app/page.tsx
+import type { Metadata } from 'next';
+import Link from 'next/link';
+
+export const metadata: Metadata = {
+  title: 'Acme - Build Better Products',
+  description: 'Build better products with the Acme platform.',
+};
+
+export default function Home() {
+  return (
+    <main>
+      <h1 className="text-4xl font-bold">Welcome to Acme</h1>
+      <p className="mt-4">
+        Build better products with our platform.
+      </p>
+      <Link
+        href="/signup"
+        className="mt-8 inline-block bg-blue-600 text-white px-6 py-3 rounded
+                   hover:bg-blue-700 focus-visible:outline focus-visible:outline-2
+                   focus-visible:outline-offset-2 focus-visible:outline-blue-600"
+      >
+        Get Started
+      </Link>
+    </main>
+  );
+}
+```
+
+```tsx
+// Also fix: src/app/layout.tsx
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+## Example 4: Svelte Component Audit
+
+```svelte
+<!-- BEFORE: src/lib/components/Accordion.svelte -->
+<script>
+  let openIndex = -1;
+  function toggle(i) { openIndex = openIndex === i ? -1 : i; }
+</script>
+
+{#each items as item, i}
+  <div class="header" on:click={() => toggle(i)}>
+    {item.title}
+  </div>
+  {#if openIndex === i}
+    <div class="content">{item.body}</div>
+  {/if}
+{/each}
+```
+
+**Violations detected:**
+
+| # | WCAG | Severity | Issue |
+|---|------|----------|-------|
+| 1 | 4.1.2 | Critical | Accordion missing ARIA roles and properties |
+| 2 | 2.1.1 | Critical | Headers not keyboard accessible |
+| 3 | 2.5.8 | Minor | Click targets may be smaller than 24x24px (NEW in WCAG 2.2) |
+
+```svelte
+<!-- AFTER: src/lib/components/Accordion.svelte -->
+<script>
+  export let items = [];
+  let openIndex = -1;
+
+  function toggle(i) {
+    openIndex = openIndex === i ? -1 : i;
+  }
+
+  function handleKeydown(event, i) {
+    if (event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault();
+      toggle(i);
+    }
+  }
+</script>
+
+<div class="accordion">
+  {#each items as item, i}
+    <h3>
+      <button
+        class="accordion-header"
+        aria-expanded={openIndex === i}
+        aria-controls="panel-{i}"
+        id="header-{i}"
+        on:click={() => toggle(i)}
+        on:keydown={(e) => handleKeydown(e, i)}
+      >
+        {item.title}
+        <span class="icon" aria-hidden="true">
+          {openIndex === i ? '−' : '+'}
+        </span>
+      </button>
+    </h3>
+    <div
+      id="panel-{i}"
+      role="region"
+      aria-labelledby="header-{i}"
+      class="accordion-content"
+      class:open={openIndex === i}
+      hidden={openIndex !== i}
+    >
+      {item.body}
+    </div>
+  {/each}
+</div>
+
+<style>
+  .accordion-header {
+    min-height: 44px; /* WCAG 2.5.8 Target Size */
+    width: 100%;
+    padding: 12px 16px;
+    cursor: pointer;
+    text-align: left;
+  }
+  .accordion-header:focus-visible {
+    outline: 2px solid #005fcc;
+    outline-offset: 2px;
+  }
+</style>
+```