From 19f7125d8add034f1bcba2b89dc40cd679d7de94 Mon Sep 17 00:00:00 2001 From: Javiera Munita Date: Fri, 13 Nov 2026 11:07:07 -0300 Subject: [PATCH] =?UTF-8?q?fix(PDYE-2318):=20configuraci=C3=B3n=20accesibi?= =?UTF-8?q?lidad=20claude?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude/CLAUDE.md | 3 + .claude/hooks/a11y-check.cjs | 137 ++++++++++++++++++ .claude/hooks/eslint-a11y.json | 48 ++++++ .claude/rules/conventions.md | 17 +++ .claude/settings.json | 16 ++ .../GUIA-EQUIPO.md | 54 +++++++ .../accesibilidad-teclado-lector/SKILL.md | 93 ++++++++++++ .../references/checklist-revision.md | 96 ++++++++++++ .../references/patrones-chakra-v1.md | 43 ++++++ .../references/puntos-criticos-ui-kit.md | 59 ++++++++ .claude/skills/playground/SKILL.md | 47 ++++++ .claude/skills/revisar-desarrollo/SKILL.md | 18 ++- .claude/skills/web-design-guidelines/SKILL.md | 9 +- .gitignore | 1 + .vscode/settings.json | 27 ---- src/main.tsx | 9 +- 16 files changed, 645 insertions(+), 32 deletions(-) create mode 100644 .claude/hooks/a11y-check.cjs create mode 100644 .claude/hooks/eslint-a11y.json create mode 100644 .claude/settings.json create mode 100644 .claude/skills/accesibilidad-teclado-lector/GUIA-EQUIPO.md create mode 100644 .claude/skills/accesibilidad-teclado-lector/SKILL.md create mode 100644 .claude/skills/accesibilidad-teclado-lector/references/checklist-revision.md create mode 100644 .claude/skills/accesibilidad-teclado-lector/references/patrones-chakra-v1.md create mode 100644 .claude/skills/accesibilidad-teclado-lector/references/puntos-criticos-ui-kit.md create mode 100644 .claude/skills/playground/SKILL.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index c651ad655..488847aa3 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -77,5 +77,8 @@ Clasifica cada pedido antes de editar: - Pedir "juntar los commits" significa solo hacer squash de los commits del usuario; los cambios propios quedan aparte para revisión. +- Accesibilidad: el código nuevo sigue `.claude/rules/conventions.md` ("Accesibilidad al escribir + componentes"). En una revisión, los arreglos mecánicos de `accesibilidad-teclado-lector` se + aplican sin preguntar (informando cada cambio, sin commitear); el resto espera al usuario. - El CI es GitHub Actions (`.github/workflows/nodejs.yml`); no existe `.gitlab-ci.yml`. GitLab solo se usa para instalar por SSH los paquetes de tipos privados `@types/eclass__*`. diff --git a/.claude/hooks/a11y-check.cjs b/.claude/hooks/a11y-check.cjs new file mode 100644 index 000000000..64d4c300c --- /dev/null +++ b/.claude/hooks/a11y-check.cjs @@ -0,0 +1,137 @@ +#!/usr/bin/env node +/** + * Hook PostToolUse (Edit|Write|MultiEdit): revisa lo básico de accesibilidad del `.tsx` que + * Claude acaba de editar, con `eslint-a11y.json` (solo ese archivo, sin tocar el eslint del repo). + * Si hay hallazgos termina con código 2 y los escribe en stderr para que Claude los corrija. + * Nunca bloquea por fallos propios (eslint ausente, timeout): en ese caso sale con 0. + * + * Está escrito en CommonJS y sin sintaxis moderna (`?.`, `??`, `node:`) porque el `node` del PATH + * del hook puede ser antiguo; eslint se ejecuta con el Node del `.nvmrc` si está en nvm. + */ +const { execFileSync } = require('child_process') +const { existsSync, readFileSync, readdirSync } = require('fs') +const { join, relative, resolve } = require('path') +const os = require('os') + +const raiz = process.env.CLAUDE_PROJECT_DIR || process.cwd() + +/** Ejecuta eslint con el Node del `.nvmrc` si existe en nvm; si no, con el Node actual. */ +function nodeParaEslint() { + try { + const version = readFileSync(join(raiz, '.nvmrc'), 'utf8').trim().replace(/^v/, '') + const base = join(process.env.NVM_DIR || join(os.homedir(), '.nvm'), 'versions/node') + const carpeta = readdirSync(base).filter((n) => n.replace(/^v/, '').indexOf(version) === 0)[0] + const bin = carpeta ? join(base, carpeta, 'bin/node') : '' + return bin && existsSync(bin) ? bin : process.execPath + } catch (e) { + return process.execPath + } +} + +function salir(codigo) { + process.exit(codigo) +} + +let entrada = {} +try { + entrada = JSON.parse(readFileSync(0, 'utf8')) +} catch (e) { + salir(0) +} + +const archivo = entrada && entrada.tool_input && entrada.tool_input.file_path +if (typeof archivo !== 'string') salir(0) + +const ruta = relative(raiz, resolve(archivo)) +const aplica = + ruta.indexOf('src/') === 0 && + /\.tsx$/.test(ruta) && + !/\.test\.tsx$/.test(ruta) && + ruta.indexOf('src/documentation/') !== 0 && + ruta !== 'src/Playground.local.tsx' && + existsSync(resolve(raiz, ruta)) +if (!aplica) salir(0) + +const eslint = resolve(raiz, 'node_modules/eslint/bin/eslint.js') +if (!existsSync(eslint)) salir(0) + +let salida = '' +try { + salida = execFileSync( + nodeParaEslint(), + [eslint, '--no-eslintrc', '-c', '.claude/hooks/eslint-a11y.json', '-f', 'json', ruta], + { cwd: raiz, encoding: 'utf8', timeout: 20000, stdio: ['ignore', 'pipe', 'ignore'] } + ) +} catch (error) { + // eslint sale con 1 cuando hay hallazgos: el JSON viene en stdout + salida = (error && error.stdout) || '' +} + +let mensajes = [] +try { + const resultado = JSON.parse(salida) + // Solo las reglas de este hook: los `eslint-disable` de otras reglas del archivo generan avisos + // de "regla no encontrada" que no importan aquí + mensajes = ((resultado[0] && resultado[0].messages) || []).filter( + (m) => m.ruleId && (m.ruleId.indexOf('jsx-a11y/') === 0 || m.ruleId === 'no-restricted-syntax') + ) +} catch (e) { + salir(0) +} + +/** + * Rangos de líneas modificadas respecto a HEAD (staged y sin stage). `null` significa "todo el + * archivo": archivo nuevo sin seguimiento o git no disponible. + */ +function lineasEditadas() { + try { + execFileSync('git', ['ls-files', '--error-unmatch', ruta], { + cwd: raiz, + stdio: ['ignore', 'ignore', 'ignore'], + }) + const diff = execFileSync('git', ['diff', '-U0', 'HEAD', '--', ruta], { + cwd: raiz, + encoding: 'utf8', + timeout: 10000, + }) + const rangos = [] + diff.split('\n').forEach((linea) => { + const h = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/.exec(linea) + if (!h) return + const inicio = Number(h[1]) + const cantidad = h[2] === undefined ? 1 : Number(h[2]) + if (cantidad > 0) rangos.push([inicio, inicio + cantidad - 1]) + }) + return rangos + } catch (e) { + return null + } +} + +// Solo hallazgos cuyo elemento (de `line` a `endLine`) se cruza con las líneas editadas: la deuda +// anterior del archivo no se reporta +const rangos = lineasEditadas() +if (rangos !== null) { + mensajes = mensajes.filter((m) => { + const fin = m.endLine || m.line + return rangos.some((r) => m.line <= r[1] && fin >= r[0]) + }) +} +if (mensajes.length === 0) salir(0) + +const lineas = mensajes.map( + (m) => '- ' + ruta + ':' + m.line + ' ' + m.message + ' [' + m.ruleId + ']' +) +process.stderr.write( + [ + 'Accesibilidad básica: ' + mensajes.length + ' hallazgo(s) en lo que acabas de editar.', + ] + .concat(lineas) + .concat([ + 'Corrige los mecánicos según la skill accesibilidad-teclado-lector (informando cada cambio);', + 'los que impliquen decisión (Box→MenuItem, aria-label, API pública) repórtalos al usuario.', + '', + ]) + .join('\n') +) +salir(2) diff --git a/.claude/hooks/eslint-a11y.json b/.claude/hooks/eslint-a11y.json new file mode 100644 index 000000000..c63b1e3a5 --- /dev/null +++ b/.claude/hooks/eslint-a11y.json @@ -0,0 +1,48 @@ +{ + "root": true, + "parser": "@typescript-eslint/parser", + "parserOptions": { "sourceType": "module", "ecmaFeatures": { "jsx": true } }, + "plugins": ["jsx-a11y"], + "settings": { + "jsx-a11y": { + "polymorphicPropName": "as", + "components": { + "Box": "div", + "Flex": "div", + "Text": "p", + "Heading": "h2", + "Link": "a", + "Image": "img", + "Button": "button", + "IconButton": "button", + "Input": "input" + } + } + }, + "rules": { + "jsx-a11y/alt-text": "error", + "jsx-a11y/anchor-has-content": "error", + "jsx-a11y/aria-props": "error", + "jsx-a11y/aria-proptypes": "error", + "jsx-a11y/aria-role": ["error", { "ignoreNonDOM": false }], + "jsx-a11y/aria-unsupported-elements": "error", + "jsx-a11y/click-events-have-key-events": "error", + "jsx-a11y/interactive-supports-focus": "error", + "jsx-a11y/no-aria-hidden-on-focusable": "error", + "jsx-a11y/no-noninteractive-tabindex": "error", + "jsx-a11y/no-static-element-interactions": "error", + "jsx-a11y/role-has-required-aria-props": "error", + "jsx-a11y/role-supports-aria-props": "error", + "no-restricted-syntax": [ + "error", + { + "selector": "Property[key.name=/^(outline|outlineWidth)$/][value.value=/^(none|0)$/]", + "message": "outline en none/0 sin reemplazo visible: usar _focusVisible (WCAG 2.4.7)" + }, + { + "selector": "JSXAttribute[name.name='outline'][value.value=/^(none|0)$/]", + "message": "outline en none/0 sin reemplazo visible: usar _focusVisible (WCAG 2.4.7)" + } + ] + } +} diff --git a/.claude/rules/conventions.md b/.claude/rules/conventions.md index f65e04caa..110e251b2 100644 --- a/.claude/rules/conventions.md +++ b/.claude/rules/conventions.md @@ -54,6 +54,23 @@ se hace al final con `/revisar-desarrollo`. `aria-label`; imágenes con `alt`; inputs con label asociado. - HTML recibido por props: sanitizar con `dompurify` antes de parsearlo con `html-react-parser`. +### Accesibilidad al escribir componentes (teclado y lector de pantalla) + +Al crear o modificar un componente con JSX (modales, menús, listas, botones), el código debe salir +ya accesible, sin esperar a la revisión: + +- Modales y menús: el foco entra al abrir y vuelve al disparador al cerrar (`returnFocusOnClose`, + `initialFocusRef`/`finalFocusRef` si hace falta); cierre con `Esc`; el modal con título enlazado + (`aria-labelledby` o `ModalHeader` de Chakra). +- Lista de elementos clicables: `MenuItem`, `button` o `a`, nunca `Box`/`div` con `onClick`. +- Botón solo con ícono: `aria-label` en español; ícono decorativo: `aria-hidden="true"`. +- Foco visible con `_focusVisible`; nunca `outline: none` sin reemplazo. +- Sin `role` inventado ni repetido sobre elementos que ya lo tienen; `id` internos con `uniqueId()`. +- Props de accesibilidad nuevas, opcionales y con un valor por defecto que mantenga el comportamiento + actual. +- Al terminar el código nuevo, aplicar la skill `accesibilidad-teclado-lector` sobre lo escrito. + Teclado y lector de pantalla no se pueden verificar leyendo código: dejar "Pendiente manual". + ## Qué NO hacer - No editar a mano `CHANGELOG.md` ni la versión de `package.json` (semantic-release). diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 000000000..38e4e7e61 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,16 @@ +{ + "hooks": { + "PostToolUse": [ + { + "matcher": "Edit|Write|MultiEdit", + "hooks": [ + { + "type": "command", + "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/a11y-check.cjs\"", + "timeout": 30 + } + ] + } + ] + } +} diff --git a/.claude/skills/accesibilidad-teclado-lector/GUIA-EQUIPO.md b/.claude/skills/accesibilidad-teclado-lector/GUIA-EQUIPO.md new file mode 100644 index 000000000..687d23f40 --- /dev/null +++ b/.claude/skills/accesibilidad-teclado-lector/GUIA-EQUIPO.md @@ -0,0 +1,54 @@ +# Cómo usar la skill de accesibilidad (guía para el equipo) + +La skill `accesibilidad-teclado-lector` ayuda a escribir y revisar código accesible de teclado y +lector de pantalla (WCAG 2.1 AA) en los componentes de ui-kit. **Propone; no verifica por sí +sola.** Lo que depende de teclado o lector de pantalla siempre hay que probarlo a mano. + +## Antes de empezar + +- Estar en la raíz de ui-kit, con Node 24.22.0 (`nvm use`) y `npm ci` hecho. +- Tener la skill disponible: viene en `.claude/skills/` del repo, no hay que instalar nada. + +## A. Al escribir un componente nuevo + +1. Pídele a Claude Code el componente, mencionando la skill. Por ejemplo: + `Crea un botón de ayuda que abra un modal. Usa la skill accesibilidad-teclado-lector.` +2. Léelo antes de aceptarlo. Debe cumplir: + - botones solo con ícono con `aria-label`, íconos decorativos con `aria-hidden`; + - ningún `role` inventado ni puesto sobre `Box` sin necesidad; + - foco visible con `_focusVisible`, nada de `outline: none`; + - props de accesibilidad nuevas opcionales, estilos solo con Chakra, JSDoc en español. +3. Corre sus pruebas (`npx vitest run `). El lint de ui-kit no revisa + accesibilidad (`jsx-a11y` está desactivado), así que no lo tomes como comprobación. +4. Haz la **prueba manual** que la skill deja como "Pendiente manual" (ver más abajo). + +## B. Al revisar un archivo que ya existe + +1. En Claude Code escribe: `/accesibilidad-teclado-lector src/ruta/al/archivo.tsx` + (acepta varios archivos o una carpeta). +2. Recibirás hallazgos con este formato: + `archivo:línea - problema (WCAG x.x.x) → corrección → cómo verificar` +3. La skill **no edita**. Elige qué hallazgos aplicar y pídele que los aplique de a uno. +4. Si el arreglo cambia un rol o un `aria-label` existente, avisa: puede romper pruebas de los + consumidores. +5. `[verificar]` significa que salió de leer código. Confírmalo en el navegador antes de darlo por + cierto. Una línea `✓ ok` no significa que todo esté bien. + +## Prueba manual mínima (5 minutos por componente) + +1. **Teclado**: en `npm run docu`, recorre todo con `Tab` y `Shift+Tab`. ¿Todo se alcanza, en + orden lógico y con el foco siempre visible? Opera con `Enter`, `Espacio`, `Esc` y flechas donde + corresponda. +2. **Modales y menús**: ábrelos con teclado. El foco entra y, al cerrar con `Esc`, vuelve al + botón que lo abrió. +3. **Lector de pantalla** (macOS): activa VoiceOver con `Cmd+F5`, navega con `Ctrl+Opción` + + flechas. Cada control debe anunciar nombre, rol y estado; los avisos dinámicos deben leerse sin + mover el foco. Desactívalo con `Cmd+F5`. +4. Antes de publicar, repetirlo en un consumidor (p. ej. v8) con yalc. + +## Lo que la skill no hace + +- No mide contraste, zoom ni movimiento reducido (fuera de esta fase). +- No reemplaza la prueba con teclado y lector de pantalla, ni una auditoría formal. +- Puede equivocarse: si un hallazgo es falso o falta uno real, avisa para ajustar + `references/` y no repetir el error. diff --git a/.claude/skills/accesibilidad-teclado-lector/SKILL.md b/.claude/skills/accesibilidad-teclado-lector/SKILL.md new file mode 100644 index 000000000..9e5274be0 --- /dev/null +++ b/.claude/skills/accesibilidad-teclado-lector/SKILL.md @@ -0,0 +1,93 @@ +--- +name: accesibilidad-teclado-lector +description: Guía y revisa accesibilidad de teclado y lector de pantalla (WCAG 2.1 AA) en los componentes de ui-kit (React desde 16.8, Chakra 1.8, librería consumida por otros fronts). Úsala al crear o modificar componentes, menús, modales o botones, y cuando se pida revisar accesibilidad. Complementa a `web-design-guidelines`; no la reemplaza ni repite sus reglas. +metadata: + version: "1.0.0" + argument-hint: +--- + +# Accesibilidad: teclado y lector de pantalla + +Meta: WCAG 2.1 AA, centrado en teclado y lectores de pantalla. El contraste, el zoom y el +movimiento reducido quedan fuera de esta fase; si los ves, menciónalos en una línea sin +desarrollarlos. El widget UserWay del consumidor no sustituye ningún arreglo. + +## Modo de trabajo + +- **Revisar**: separa los hallazgos en dos clases. + - **Mecánicos**: se aplican de inmediato, sin pedir confirmación, con el cambio mínimo y solo + en los archivos del alcance. Son únicamente estos: + 1. `aria-hidden="true"` en un ícono claramente decorativo (acompañado de texto visible). + 2. `outline: none` / `boxShadow: 'none'` en foco → reemplazo con `_focusVisible` ya usado en + el mismo componente o en `NavBarButton`. + 3. Quitar un `role` repetido en un elemento que ya lo tiene, o un `role` con un nombre + inventado, solo si ninguna prueba ni estilo lo usa como selector. + 4. `alt=""` en una imagen decorativa sin `alt`. + 5. Quitar `aria-hidden` de un contenedor con elementos enfocables o de lectura. + - **Con decisión del usuario**: todo lo demás (cambiar `Box` por `MenuItem`, cualquier + `aria-label` nuevo o cambiado, props nuevas, cambios de API pública, foco en modales, + anuncios) se reporta con el arreglo propuesto y no se aplica hasta que el usuario elija. + - Tras aplicar mecánicos: lista cada cambio (`archivo:línea`, antes → después y criterio WCAG), + corre `npx prettier --write` y `npx eslint` sobre los archivos tocados y las pruebas de esos + archivos (`npx vitest run `); si una falla, revierte ese cambio y pásalo a "con + decisión". No commitees. +- **Escribir**: aplica las reglas al código nuevo con los cambios mínimos, solo Chakra (`sx`, + `_focusVisible`), sin styled-components nuevos, con prueba y `getByRole` cuando corresponda. +- Leer el código no verifica teclado ni lector de pantalla. Todo lo que dependa de eso queda como + tarea manual pendiente del usuario, nunca como "verificado". +- ui-kit es una librería: un arreglo no puede cambiar la API pública. Props nuevas siempre + opcionales y con un valor por defecto que mantenga el comportamiento actual (ver + `.claude/rules/conventions.md`). + +## Pasos + +1. **Alcance**: los archivos indicados; si no hay, el diff (`git diff main...HEAD`): los `.tsx` + con JSX (sin `src/documentation`) y también hooks que manejen foco, modales o anuncios. +2. **Checklist**: aplica `references/checklist-revision.md` en este orden de prioridad: + roles ARIA válidos → nombre accesible → teclado y foco → anuncios dinámicos → estructura. +3. **Hijos compartidos**: el problema puede estar en un componente reutilizado (`Icon`, `Icons/*`, + `NavBarButton`, `BtnLink`, `BtnTertiary`) y no en el archivo revisado. Ábrelos antes de dar un + archivo por `✓ ok`. Abre primero los que renderizan listas o ítems clicables (`onClick`, + `map`). Si algún hijo no lo abres, dilo en la primera línea del informe, no solo al final. +4. **Patrones por librería**: si el código usa Chakra o los botones y modales propios de ui-kit, + consulta `references/patrones-chakra-v1.md`. +5. **Puntos críticos de ui-kit**: si toca el calendario, el menú de usuario, `NavBarButton` o los + íconos, consulta `references/puntos-criticos-ui-kit.md`. +6. **Reglas básicas**: aplica también las de `web-design-guidelines` (aria-label en íconos, + `div`/`Box` con `onClick`, `outline: none`, `aria-live` básico) sobre los archivos y sus + hijos, salvo que el usuario ya haya corrido esa guía en esta revisión. + +## Formato de salida + +Agrupado por archivo, un hallazgo por línea: + +`archivo:línea - problema (WCAG x.x.x) → corrección → cómo verificar` + +- Marca `[verificar]` cuando el hallazgo salga de leer código y no de una herramienta. +- Archivo sin hallazgos: `✓ ok` (solo tras revisar sus hijos compartidos). +- Lista solo hallazgos de accesibilidad con texto completo. No numeres ítems vacíos, "no es + hallazgo" ni observaciones de código ajeno sin relación (menciónalas en una línea aparte). +- Cita `archivo:línea` solo después de leer el archivo con numeración de líneas y comprobar que la + ruta existe. Si no puedes confirmarla, cita el archivo sin línea. Nunca des rutas ni líneas de + memoria. Una línea citada no puede superar el total de líneas del archivo leído. +- Si hay cambios sin commitear, avísalo: pueden desplazar líneas o incluir código de prueba. +- Cierra con "Pendiente manual": los pasos de teclado/lector que el usuario debe probar. +- Si añades un "Siguiente paso", que sean solo arreglos de hallazgos ya listados; no agregues + ítems nuevos ahí. + +## Cómo comprobar + +- Lint: `plugin:jsx-a11y` está comentado en `.eslintrc.json`, así que `npx eslint` **no** detecta + problemas de accesibilidad en este repo. Hay una configuración aparte, solo para esto: + `npx eslint --no-eslintrc -c .claude/hooks/eslint-a11y.json ` (roles ARIA, `alt`, + `onClick` sin teclado, `outline: none`; mapea `Box`, `Button`, `Link`, etc. de Chakra). El hook + `.claude/hooks/a11y-check.cjs` la corre solo sobre cada `.tsx` de `src` (sin pruebas ni + documentación) que Claude edita y le devuelve solo los hallazgos que se cruzan con las líneas + modificadas (respecto a `HEAD`; en un archivo nuevo, todos). La deuda anterior del archivo no + se reporta en el hook: aparece en una revisión completa y se informa aparte. +- Límite del lint: no ve dentro de componentes propios. Un `onClick` pasado a un hijo (como + `EventsList` en `EventsGroup.tsx`) no se detecta: sigue el paso "Hijos compartidos". +- Pruebas: `npx vitest run ` con consultas `getByRole`/`getByLabelText` + (Testing Library) y `userEvent` para teclado. Una prueba verde no demuestra accesibilidad. +- Probar a mano en la documentación (`npm run docu`) o, antes de publicar, en un consumidor con + yalc (ver `.claude/rules/commands.md`). Teclado y lector de pantalla se prueban a mano. diff --git a/.claude/skills/accesibilidad-teclado-lector/references/checklist-revision.md b/.claude/skills/accesibilidad-teclado-lector/references/checklist-revision.md new file mode 100644 index 000000000..0e9e89621 --- /dev/null +++ b/.claude/skills/accesibilidad-teclado-lector/references/checklist-revision.md @@ -0,0 +1,96 @@ +# Checklist de revisión + +Orden de prioridad. Cada punto cita el criterio WCAG 2.1 principal. + +## 1. Roles y atributos ARIA válidos (4.1.2) + +- `role` solo con valores de WAI-ARIA (`button`, `dialog`, `tab`...). Nunca el nombre del + componente o de una clase (`role="Icon"`). +- Si el elemento ya tiene el rol por su etiqueta (`