Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .claude/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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__*`.
137 changes: 137 additions & 0 deletions .claude/hooks/a11y-check.cjs
Original file line number Diff line number Diff line change
@@ -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)
48 changes: 48 additions & 0 deletions .claude/hooks/eslint-a11y.json
Original file line number Diff line number Diff line change
@@ -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)"
}
]
}
}
17 changes: 17 additions & 0 deletions .claude/rules/conventions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
16 changes: 16 additions & 0 deletions .claude/settings.json
Original file line number Diff line number Diff line change
@@ -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
}
]
}
]
}
}
54 changes: 54 additions & 0 deletions .claude/skills/accesibilidad-teclado-lector/GUIA-EQUIPO.md
Original file line number Diff line number Diff line change
@@ -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 <ruta del .test.tsx>`). 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.
93 changes: 93 additions & 0 deletions .claude/skills/accesibilidad-teclado-lector/SKILL.md
Original file line number Diff line number Diff line change
@@ -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: <archivo-o-carpeta>
---

# 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 <rutas>`); 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 <archivos>` (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 <rutas de .test.tsx>` 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.
Loading
Loading