accessibility-hub 0.1.2 → 0.2.0

package/EXAMPLES.md

@@ -7,6 +7,7 @@ Ejemplos concretos de inputs y outputs para cada herramienta MCP.
 - [analyze-with-axe](#analyze-with-axe)
 - [analyze-with-pa11y](#analyze-with-pa11y)
 - [analyze-with-eslint](#analyze-with-eslint)
+- [analyze-contrast](#analyze-contrast)
 - [analyze-all](#analyze-all)
 
 ---
@@ -343,6 +344,215 @@ Ejemplos concretos de inputs y outputs para cada herramienta MCP.
 
 ---
 
+## analyze-contrast
+
+### Ejemplo 1: Análisis básico de contraste
+
+**Input:**
+```json
+{
+  "url": "https://example.com"
+}
+```
+
+**Output:**
+```json
+{
+  "success": true,
+  "target": "https://example.com",
+  "wcagLevel": "AA",
+  "issueCount": 3,
+  "issues": [
+    {
+      "id": "contrast-0",
+      "ruleId": "color-contrast",
+      "tool": "contrast-analyzer",
+      "severity": "serious",
+      "wcag": {
+        "criterion": "1.4.3",
+        "level": "AA",
+        "principle": "perceivable",
+        "version": "2.1",
+        "title": "Contrast (Minimum)"
+      },
+      "location": {
+        "selector": "p.subtitle",
+        "snippet": "<p class=\"subtitle\">Light gray text on white</p>"
+      },
+      "message": "Contrast ratio 2.5:1 does not meet AA requirements (4.5:1 required for normal text)",
+      "humanContext": "Users with low vision or color blindness may have difficulty reading this text. The current contrast of 2.5:1 is below the AA threshold of 4.5:1.",
+      "suggestedActions": [
+        "Increase contrast ratio to at least 4.5:1",
+        "Consider using #767676 as the text color"
+      ],
+      "affectedUsers": ["low-vision", "color-blind"],
+      "contrastData": {
+        "foreground": "rgb(180, 180, 180)",
+        "background": "rgb(255, 255, 255)",
+        "currentRatio": 2.5,
+        "requiredRatio": 4.5,
+        "isLargeText": false,
+        "fontSize": 16,
+        "fontWeight": 400,
+        "suggestedFix": {
+          "foreground": "#767676",
+          "background": "#ffffff",
+          "newRatio": 4.54
+        }
+      }
+    }
+  ],
+  "summary": {
+    "total": 25,
+    "passing": 22,
+    "failing": 3,
+    "byTextSize": {
+      "normalText": { "passing": 18, "failing": 3 },
+      "largeText": { "passing": 4, "failing": 0 }
+    }
+  },
+  "duration": 1234
+}
+```
+
+---
+
+### Ejemplo 2: Análisis con nivel AAA
+
+**Input:**
+```json
+{
+  "url": "https://example.com",
+  "options": {
+    "wcagLevel": "AAA"
+  }
+}
+```
+
+**Output:**
+```json
+{
+  "success": true,
+  "target": "https://example.com",
+  "wcagLevel": "AAA",
+  "issueCount": 8,
+  "issues": [
+    {
+      "id": "contrast-0",
+      "ruleId": "color-contrast",
+      "tool": "contrast-analyzer",
+      "severity": "moderate",
+      "wcag": {
+        "criterion": "1.4.6",
+        "level": "AAA",
+        "principle": "perceivable",
+        "version": "2.1",
+        "title": "Contrast (Enhanced)"
+      },
+      "message": "Contrast ratio 5.2:1 does not meet AAA requirements (7:1 required for normal text)",
+      "contrastData": {
+        "foreground": "rgb(100, 100, 100)",
+        "background": "rgb(255, 255, 255)",
+        "currentRatio": 5.2,
+        "requiredRatio": 7,
+        "isLargeText": false
+      }
+    }
+  ],
+  "summary": {
+    "total": 25,
+    "passing": 17,
+    "failing": 8
+  },
+  "duration": 1456
+}
+```
+
+---
+
+### Ejemplo 3: Análisis de sección específica
+
+**Input:**
+```json
+{
+  "url": "https://example.com",
+  "options": {
+    "selector": "#main-content",
+    "suggestFixes": true
+  }
+}
+```
+
+---
+
+### Ejemplo 4: HTML con análisis de contraste
+
+**Input:**
+```json
+{
+  "html": "<div style='background: #fff'><p style='color: #999'>Low contrast text</p><h1 style='color: #333'>Good contrast heading</h1></div>",
+  "options": {
+    "wcagLevel": "AA",
+    "includePassingElements": true
+  }
+}
+```
+
+**Output:**
+```json
+{
+  "success": true,
+  "target": "[html content]",
+  "wcagLevel": "AA",
+  "issueCount": 2,
+  "issues": [
+    {
+      "id": "contrast-0",
+      "ruleId": "color-contrast",
+      "severity": "serious",
+      "message": "Contrast ratio 2.85:1 does not meet AA requirements (4.5:1 required for normal text)",
+      "contrastData": {
+        "foreground": "rgb(153, 153, 153)",
+        "background": "rgb(255, 255, 255)",
+        "currentRatio": 2.85,
+        "requiredRatio": 4.5,
+        "isLargeText": false,
+        "suggestedFix": {
+          "foreground": "#767676",
+          "background": "#ffffff",
+          "newRatio": 4.54
+        }
+      }
+    },
+    {
+      "id": "contrast-1",
+      "ruleId": "color-contrast",
+      "severity": "minor",
+      "message": "Contrast ratio 12.63:1 meets AA requirements (3:1 required for large text)",
+      "contrastData": {
+        "foreground": "rgb(51, 51, 51)",
+        "background": "rgb(255, 255, 255)",
+        "currentRatio": 12.63,
+        "requiredRatio": 3,
+        "isLargeText": true
+      }
+    }
+  ],
+  "summary": {
+    "total": 2,
+    "passing": 1,
+    "failing": 1,
+    "byTextSize": {
+      "normalText": { "passing": 0, "failing": 1 },
+      "largeText": { "passing": 1, "failing": 0 }
+    }
+  },
+  "duration": 89
+}
+```
+
+---
+
 ## analyze-all
 
 ### Ejemplo 1: Análisis combinado básico
@@ -550,16 +760,17 @@ Ejemplos concretos de inputs y outputs para cada herramienta MCP.
 
 ## Resumen de Diferencias
 
-| Característica | axe-core | Pa11y | ESLint |
-|----------------|----------|-------|--------|
-| **Target** | URL/HTML | URL/HTML | Archivos .vue |
-| **Selector** | CSS compacto | CSS completo | Línea/columna |
-| **Severidades** | 4 niveles | 3 tipos | 2 niveles (warn/error) |
-| **Snippet** | ✅ | ✅ | ✅ |
-| **Confidence** | ✅ | ✅ | Siempre 1 |
-| **Browser** | Puppeteer | Puppeteer | - |
-| **Velocidad** | ~2-3s | ~2s | <1s |
-| **Falsos positivos** | Pocos | Moderados | Muy pocos |
+| Característica | axe-core | Pa11y | ESLint | Contrast |
+|----------------|----------|-------|--------|----------|
+| **Target** | URL/HTML | URL/HTML | Archivos .vue | URL/HTML |
+| **Selector** | CSS compacto | CSS completo | Línea/columna | CSS compacto |
+| **Severidades** | 4 niveles | 3 tipos | 2 niveles | 4 niveles |
+| **Snippet** | ✅ | ✅ | ✅ | ✅ |
+| **Confidence** | ✅ | ✅ | Siempre 1 | Siempre 1 |
+| **Browser** | Puppeteer | Puppeteer | - | Puppeteer |
+| **Velocidad** | ~2-3s | ~2s | <1s | ~1-2s |
+| **Falsos positivos** | Pocos | Moderados | Muy pocos | Muy pocos |
+| **Sugerencias de fix** | - | - | - | ✅ Colores |
 
 ---
 

package/README.md

@@ -9,6 +9,7 @@ Servidor MCP para orquestación de herramientas de accesibilidad web (axe-core,
   - [analyze-with-axe](#analyze-with-axe)
   - [analyze-with-pa11y](#analyze-with-pa11y)
   - [analyze-with-eslint](#analyze-with-eslint)
+  - [analyze-contrast](#analyze-contrast)
   - [analyze-all ⭐](#analyze-all-)
 - [Contexto Humano Enriquecido ✨](#contexto-humano-enriquecido-)
 - [Estructura del Proyecto](#estructura-del-proyecto)
@@ -104,6 +105,82 @@ Analiza archivos Vue.js para problemas de accesibilidad mediante análisis está
 - `directory`: Directorio a analizar recursivamente
 - `code`: Código Vue inline a analizar
 
+### `analyze-contrast`
+
+Analiza una página web o contenido HTML para detectar problemas de contraste de color según WCAG 2.1.
+
+**Parámetros:**
+
+| Parámetro | Tipo | Requerido | Descripción |
+|-----------|------|-----------|-------------|
+| `url` | string | url o html | URL de la página a analizar |
+| `html` | string | url o html | Contenido HTML raw a analizar |
+| `options.wcagLevel` | "AA" \| "AAA" | No | Nivel WCAG: AA (4.5:1 normal, 3:1 grande) o AAA (7:1 normal, 4.5:1 grande). Default: AA |
+| `options.suggestFixes` | boolean | No | Sugerir correcciones de color (default: true) |
+| `options.includePassingElements` | boolean | No | Incluir elementos que pasan en los resultados (default: false) |
+| `options.selector` | string | No | Selector CSS para limitar el análisis a un elemento específico |
+| `options.browser.waitForSelector` | string | No | Selector CSS a esperar antes del análisis |
+| `options.browser.viewport` | object | No | Dimensiones del viewport |
+| `options.browser.ignoreHTTPSErrors` | boolean | No | Ignorar errores de certificado SSL (default: false) |
+
+**Ejemplo de respuesta:**
+
+```json
+{
+  "success": true,
+  "target": "https://example.com",
+  "wcagLevel": "AA",
+  "issueCount": 2,
+  "issues": [
+    {
+      "id": "contrast-0",
+      "ruleId": "color-contrast",
+      "tool": "contrast-analyzer",
+      "severity": "serious",
+      "wcag": {
+        "criterion": "1.4.3",
+        "level": "AA",
+        "principle": "perceivable"
+      },
+      "location": {
+        "selector": "p.subtitle",
+        "snippet": "<p class=\"subtitle\">Texto de ejemplo</p>"
+      },
+      "message": "Contrast ratio 3.2:1 does not meet AA requirements (4.5:1 required for normal text)",
+      "contrastData": {
+        "foreground": "rgb(150, 150, 150)",
+        "background": "rgb(255, 255, 255)",
+        "currentRatio": 3.2,
+        "requiredRatio": 4.5,
+        "isLargeText": false,
+        "fontSize": 16,
+        "fontWeight": 400,
+        "suggestedFix": {
+          "foreground": "#767676",
+          "background": "#ffffff",
+          "newRatio": 4.54
+        }
+      },
+      "affectedUsers": ["low-vision", "color-blind"]
+    }
+  ],
+  "summary": {
+    "total": 15,
+    "passing": 13,
+    "failing": 2,
+    "byTextSize": {
+      "normalText": { "passing": 10, "failing": 2 },
+      "largeText": { "passing": 3, "failing": 0 }
+    }
+  },
+  "duration": 1543
+}
+```
+
+**Criterios WCAG:**
+- 1.4.3 Contraste (Mínimo) - Nivel AA
+- 1.4.6 Contraste (Mejorado) - Nivel AAA
+
 ### `analyze-all` ⭐
 
 **Tool de síntesis para análisis web** que ejecuta axe-core y Pa11y en paralelo y combina los resultados.
@@ -160,22 +237,34 @@ src/
 │   ├── base.ts         # Clase base para adaptadores
 │   ├── axe.ts          # Adaptador axe-core con Puppeteer
 │   ├── pa11y.ts        # Adaptador Pa11y
-│   └── eslint.ts       # Adaptador ESLint Vue a11y
+│   ├── eslint.ts       # Adaptador ESLint Vue a11y
+│   └── contrast.ts     # Adaptador de análisis de contraste
 ├── tools/
 │   ├── base.ts         # Utilidades para tools MCP
 │   ├── axe.ts          # Tool analyze-with-axe
 │   ├── pa11y.ts        # Tool analyze-with-pa11y
 │   ├── eslint.ts       # Tool analyze-with-eslint
+│   ├── contrast.ts     # Tool analyze-contrast
 │   └── analyze-all.ts  # Tool de síntesis multi-herramienta
 ├── types/              # Schemas Zod (inputs, outputs, validación)
+│   └── contrast.ts     # Tipos para análisis de contraste
 ├── normalizers/        # Transformación a formato unificado
-└── utils/              # Logger, contexto WCAG
+└── utils/
+    ├── logger.ts       # Logging estructurado
+    ├── wcag-context.ts # Contexto WCAG
+    └── color-analysis/ # Utilidades de análisis de color
+        ├── contrast.ts   # Cálculo de ratios de contraste
+        ├── converters.ts # Conversión entre formatos de color
+        └── parsers.ts    # Parseo de colores CSS
 
 tests/
 ├── adapters/           # Tests unitarios de adaptadores
+│   └── contrast.test.ts
 ├── tools/              # Tests de integración de tools
 ├── fixtures/           # HTML con problemas de accesibilidad conocidos
-└── helpers/            # Utilidades para tests (mock server, etc.)
+├── helpers/            # Utilidades para tests (mock server, etc.)
+└── utils/
+    └── color-analysis/ # Tests de utilidades de color
 ```
 
 ## Scripts
@@ -315,6 +404,8 @@ Una vez configurado, puedes usar prompts como:
 - "Revisa este HTML para problemas de accesibilidad: `<img src='foto.jpg'>`"
 - "Analiza los archivos Vue en src/components/ para problemas de accesibilidad" (usa analyze-with-eslint)
 - "Compara los resultados de axe-core y Pa11y en mi landing page" (usa analyze-all)
+- "Verifica el contraste de colores de mi página web" (usa analyze-contrast)
+- "Analiza si los colores de texto cumplen con WCAG AAA" (usa analyze-contrast con wcagLevel: AAA)
 
 ### Desarrollo Local
 

package/USAGE.md

@@ -101,6 +101,23 @@ Compara los resultados de axe-core y Pa11y en https://ejemplo.com
 
 ---
 
+### 6. Análisis de Contraste de Colores
+
+**Prompt:**
+```
+Verifica si los colores de texto de https://mi-sitio.com cumplen con WCAG AA
+```
+
+**¿Qué herramienta se usará?**  
+→ `analyze-contrast`
+
+**Resultado esperado:**
+- Ratio de contraste actual vs requerido
+- Sugerencias de colores que cumplan WCAG
+- Estadísticas por tipo de texto (normal/grande)
+
+---
+
 ## Ejemplos por Herramienta
 
 ### `analyze-with-axe`
@@ -187,6 +204,61 @@ Analiza todos los archivos Vue en src/components/ para problemas de accesibilida
 
 ---
 
+### `analyze-contrast`
+
+#### Ejemplo 1: Análisis básico de contraste
+```
+Verifica el contraste de colores de https://example.com
+```
+
+#### Ejemplo 2: Análisis con nivel AAA
+```
+Analiza el contraste de https://example.com con nivel WCAG AAA
+```
+
+**Input equivalente:**
+```json
+{
+  "url": "https://example.com",
+  "options": {
+    "wcagLevel": "AAA"
+  }
+}
+```
+
+#### Ejemplo 3: Análisis de sección específica
+```
+Verifica el contraste solo del header de mi página
+```
+
+**Input equivalente:**
+```json
+{
+  "url": "https://example.com",
+  "options": {
+    "selector": "header",
+    "suggestFixes": true
+  }
+}
+```
+
+#### Ejemplo 4: Incluir elementos que pasan
+```
+Muéstrame el contraste de todos los elementos, incluyendo los que pasan
+```
+
+**Input equivalente:**
+```json
+{
+  "url": "https://example.com",
+  "options": {
+    "includePassingElements": true
+  }
+}
+```
+
+---
+
 ### `analyze-all`
 
 #### Ejemplo 1: Análisis completo
@@ -427,6 +499,38 @@ el issue WCAG 1.1.1 (Contenido no textual):
 }
 ```
 
+### 4. Análisis de Contraste con Nivel AAA
+
+Para proyectos que requieren máxima accesibilidad:
+
+```json
+{
+  "url": "https://example.com",
+  "options": {
+    "wcagLevel": "AAA",
+    "suggestFixes": true
+  }
+}
+```
+
+**Ratios requeridos:**
+- **AA:** 4.5:1 (texto normal), 3:1 (texto grande)
+- **AAA:** 7:1 (texto normal), 4.5:1 (texto grande)
+
+### 5. Contraste de Sección Específica
+
+Analiza solo el contraste de una parte de la página:
+
+```json
+{
+  "url": "https://example.com",
+  "options": {
+    "selector": ".hero-section",
+    "includePassingElements": false
+  }
+}
+```
+
 ---
 
 ## Preguntas Frecuentes
@@ -435,6 +539,7 @@ el issue WCAG 1.1.1 (Contenido no textual):
 
 - **Para web deployada:** `analyze-all` (cobertura máxima)
 - **Para código Vue:** `analyze-with-eslint` (rápido, sin browser)
+- **Para verificar colores:** `analyze-contrast` (con sugerencias de corrección)
 
 ### ¿Cómo manejar falsos positivos?