accessibility-compliance

Visión general de accessibility-compliance skill

Qué hace accessibility-compliance skill

La accessibility-compliance skill ayuda a un agente a generar orientación de accesibilidad lista para implementar en trabajo de UI web y móvil, con un foco claro en WCAG 2.2, uso de ARIA, acceso por teclado, compatibilidad con lectores de pantalla y accesibilidad móvil. Está pensada para equipos que trabajan sobre interfaces reales, no solo para redactar una checklist genérica de accesibilidad.

Quién debería instalar accessibility-compliance

Esta skill encaja bien para:

• auditores UX que necesitan accessibility-compliance for UX Audit
• ingenieros frontend que corrigen problemas de accesibilidad en componentes
• equipos de design systems que definen patrones de interacción accesibles
• equipos de producto que lanzan formularios, diálogos, menús y otras UI interactivas
• equipos móviles o multiplataforma que necesitan orientación teniendo en cuenta VoiceOver y TalkBack

Si tu trabajo consiste en “convertir esta pantalla o componente en algo más cercano al cumplimiento de WCAG con correcciones concretas”, esta skill resulta más útil que un prompt amplio de diseño.

Por qué esta skill es diferente de un prompt genérico

El valor principal de la accessibility-compliance skill es que orienta el modelo hacia patrones prácticos de implementación de accesibilidad, en lugar de quedarse en principios vagos. El repositorio incluye referencias específicas sobre:

• references/wcag-guidelines.md
• references/aria-patterns.md
• references/mobile-accessibility.md

Eso la hace más adecuada para tareas como elegir HTML semántico en lugar de ARIA, estructurar formularios accesibles, mejorar el comportamiento de teclado o revisar la guía de tamaño de objetivos táctiles en móvil.

Qué suele importar antes de instalarla

La mayoría de los usuarios que evalúan accessibility-compliance install quieren saber:

• si ofrece correcciones concretas orientadas a código en lugar de lenguaje de políticas
• si cubre tanto necesidades web como móviles
• si sirve tanto para auditorías como para implementación
• si toma postura sobre semántica nativa frente a ARIA
• si puede reducir idas y vueltas al revisar componentes de UI

En esos puntos, esta skill se ve sólida. Su principal diferenciación es la amplitud práctica: reúne conceptos de WCAG, patrones ARIA y accesibilidad móvil en un mismo paquete.

Casos en los que encaja bien y casos en los que no

Mejor encaje:

• auditar componentes interactivos
• corregir problemas de accesibilidad en código existente
• planificar comportamiento accesible para diálogos, acordeones, formularios y navegación
• revisar orden de foco, etiquetas, anuncios y compatibilidad con reduced motion

No encaja bien para:

• interpretación legal de cumplimiento en una jurisdicción concreta
• configurar por sí sola pruebas automatizadas
• crítica visual al nivel de píxel no relacionada con accesibilidad
• APIs nativas específicas de plataforma en profundidad más allá de la guía referenciada

Cómo usar accessibility-compliance skill

Contexto de instalación e invocación

El SKILL.md de origen no incluye un comando de instalación, así que los usuarios del directorio normalmente la añadirán desde el repo:

npx skills add https://github.com/wshobson/agents --skill accessibility-compliance

Después, conviene invocarla dándole al agente una tarea concreta de accesibilidad, no solo “revisa la accesibilidad”. La skill funciona mejor cuando la solicitud incluye un componente, flujo o pantalla con suficiente estructura como para poder revisarla.

Lee primero estos archivos

Para adoptarla rápido, empieza aquí:

1. plugins/ui-design/skills/accessibility-compliance/SKILL.md
2. plugins/ui-design/skills/accessibility-compliance/references/wcag-guidelines.md
3. plugins/ui-design/skills/accessibility-compliance/references/aria-patterns.md
4. plugins/ui-design/skills/accessibility-compliance/references/mobile-accessibility.md

Ese orden de lectura refleja cómo suelen trabajar la mayoría de los equipos: primero el objetivo de cumplimiento, después los patrones de implementación y, por último, los casos límite por plataforma.

Qué información necesita la skill para funcionar bien

La calidad de accessibility-compliance usage depende mucho de lo específico que sea tu input. Proporciona:

• tipo de componente o página
• código o marcado actual
• framework (React, Next.js, Vue, plain HTML, React Native)
• comportamiento de interacción
• estándar objetivo, normalmente WCAG 2.2 AA
• alcance por dispositivo: desktop web, mobile web, iOS, Android
• problemas conocidos detectados por herramientas de auditoría o tests con usuarios

Input débil:

• “Make this accessible.”

Input sólido:

• “Review this React modal for WCAG 2.2 AA. Check keyboard trap behavior, focus return, accessible name/description, escape handling, and screen reader announcements. Suggest code changes before release.”

Convierte un objetivo difuso en un buen prompt

Un buen prompt de accessibility-compliance guide suele tener cinco partes:

1. UI objetivo
2. interacciones de usuario
3. objetivo de conformidad
4. entregable esperado
5. restricciones

Ejemplo:

• “Use the accessibility-compliance skill to audit this checkout form for WCAG 2.2 AA. Identify failures by issue, explain user impact, and provide corrected JSX for labels, error messaging, field grouping, and keyboard flow. Keep the current visual design if possible.”

Esto funciona mejor que pedir simplemente “best practices”, porque obliga al modelo a generar una respuesta que se pueda corregir e implementar.

Mejor flujo de trabajo para una UX audit con accessibility-compliance

Para accessibility-compliance for UX Audit, usa esta secuencia:

1. pedir detección de problemas
2. pedir severidad e impacto en usuarios
3. pedir correcciones mapeadas a cada problema
4. pedir marcado revisado o código del componente
5. pedir una checklist de retest

Así evitas un fallo habitual: que la primera respuesta se quede demasiado en lo conceptual. La skill aporta más valor cuando la empujas desde los hallazgos de auditoría hasta los detalles de implementación.

Úsala para componentes, no solo para páginas

La skill destaca especialmente en patrones de interacción reutilizables. Buenos objetivos incluyen:

• diálogos y focus traps
• acordeones
• menús y disclosures
• formularios y validación
• tabs
• carousels
• icon buttons
• objetivos táctiles en móvil

Son precisamente los casos en los que los prompts genéricos suelen abusar de ARIA o pasar por alto el comportamiento de teclado y lector de pantalla.

Lo que implican las referencias en la práctica

Las referencias incluidas sugieren tres reglas de trabajo importantes:

• priorizar HTML semántico antes de añadir ARIA
• tratar WCAG 2.2 AA como base por defecto
• tener en cuenta la accesibilidad móvil, no solo el uso de teclado en escritorio

Esto importa en el uso real. Un prompt decente debería pedir explícitamente al agente que minimice el ARIA innecesario y justifique cualquier atributo ARIA que añada.

Patrón de prompt para obtener mejores resultados con accessibility-compliance

Usa un formato de solicitud como este:

• Context: “This is a React checkout drawer.”
• Target: “Meet WCAG 2.2 AA.”
• Review scope: “Keyboard access, focus order, visible labels, error association, live region announcements.”
• Constraints: “Do not rewrite the design system API.”
• Deliverable: “Return prioritized issues, corrected JSX, and a manual test checklist.”

Esta estructura produce de forma consistente un mejor accessibility-compliance usage que las peticiones de revisión abiertas.

Qué esperar de la salida

Una buena respuesta de la accessibility-compliance skill debería incluir:

• lista de problemas vinculados a impacto en usuarios
• referencias a principios o criterios de accesibilidad
• cambios concretos de marcado o código
• notas sobre comportamiento de teclado y foco
• orientación sobre naming y anuncios para lectores de pantalla
• notas específicas para móvil cuando correspondan

Si la respuesta se queda en principios sin correcciones a nivel de código, tu prompt es demasiado amplio.

Preguntas frecuentes sobre accessibility-compliance skill

¿accessibility-compliance sirve para principiantes?

Sí, si ya conoces la estructura básica de una UI. La skill aporta más valor cuando puedes proporcionar marcado, componentes o hallazgos de auditoría. Los principiantes también pueden usarla, pero deberían contar con hacer preguntas de seguimiento sobre por qué importan determinadas decisiones de semántica o ARIA.

¿Es mejor que un prompt normal de accesibilidad?

Normalmente sí para trabajo de implementación. Un prompt normal puede devolver orientación genérica como “add alt text” o “ensure keyboard navigation”. La accessibility-compliance skill tiene más probabilidades de mantenerse anclada en WCAG 2.2, patrones ARIA y consideraciones de accesibilidad móvil presentes en las referencias del repositorio.

¿Sustituye las pruebas automatizadas de accesibilidad?

No. Complementa las herramientas automáticas y la revisión manual. Úsala para interpretar problemas, proponer correcciones y revisar comportamientos de componentes que las herramientas estáticas suelen pasar por alto, como la gestión del foco, el momento de los anuncios o detalles de interacción móvil.

¿Cuándo no debería usar accessibility-compliance?

Evítala cuando necesites:

• asesoramiento legal o decisiones de certificación
• escaneo totalmente automatizado de un código base completo
• detalles muy profundos de plataformas móviles nativas más allá de los patrones referenciados
• crítica UX que no sea de accesibilidad

Es una skill de orientación, no una garantía de cumplimiento.

¿Da buen soporte a la accesibilidad móvil?

Razonablemente bien para una skill de IA. La referencia específica mobile-accessibility.md cubre tamaño de objetivos táctiles, espaciado y consideraciones de lectores de pantalla para iOS y Android. Eso hace que esta skill sea más creíble para revisión móvil que los prompts de accesibilidad centrados solo en web de escritorio.

¿Puedo usarla para trabajo de design system?

Sí. Encaja muy bien para definir valores por defecto accesibles en componentes reutilizables, especialmente cuando la semántica, el manejo por teclado, el estado ARIA y la gestión del foco deben mantenerse consistentes en muchos productos.

Cómo mejorar accessibility-compliance skill

Dale a la skill artefactos reales, no resúmenes

La forma más rápida de mejorar los resultados de accessibility-compliance es proporcionar JSX, HTML, código de React Native, capturas con anotaciones o una descripción paso a paso de la interacción. La skill no puede inferir de forma fiable el orden de foco, las etiquetas o los anuncios a partir de resúmenes vagos del producto.

Pide mapeo de problemas, no solo recomendaciones

Una solicitud más fuerte sería:

• “List each issue, affected users, violated principle or criterion, and exact fix.”

Esto obliga al modelo a generar una salida auditable. Sin esa estructura, las respuestas tienden a derivar hacia consejos genéricos.

Indica qué nivel de cambio aceptas

Las correcciones de accesibilidad suelen implicar compromisos con las restricciones del design system. Especifica si el agente puede:

• cambiar solo el marcado
• añadir ARIA solo cuando sea necesario
• reestructurar la jerarquía del componente
• modificar el copy para ganar claridad
• cambiar patrones de interacción si el diseño actual es inaccesible

Esto cambia la calidad del resultado más de lo que la mayoría de usuarios espera.

Fallo habitual: abusar de ARIA

Un problema previsible en trabajo de accesibilidad es añadir ARIA cuando el HTML nativo funcionaría mejor. Para mejorar la salida, indícalo explícitamente:

• “Prefer native semantic elements and only use ARIA when native semantics are insufficient.”

Esa instrucción está alineada con la referencia ARIA del repositorio y reduce correcciones de baja calidad.

Fallo habitual: olvidar los cambios de estado

Muchas respuestas iniciales detectan etiquetas y foco, pero pasan por alto el comportamiento dinámico. Pide específicamente:

• entrada y retorno del foco
• anuncios de estado expanded/collapsed
• asociación de errores de validación
• mensajes de estado asíncronos con live regions
• consideraciones de reduced motion y alto contraste cuando aplique

Estos detalles mejoran materialmente la utilidad de la accessibility-compliance guide.

Itera después de la primera respuesta

Tras la auditoría inicial, continúa con alguna de estas opciones:

• “Rewrite the component with the fixes applied.”
• “Prioritize only release-blocking issues.”
• “Convert this into QA test steps.”
• “Explain what should be tested with screen readers.”
• “Separate WCAG AA requirements from nice-to-have AAA improvements.”

Así conviertes la skill de revisor en una ayuda real para la entrega.

Usa las referencias del repositorio de forma quirúrgica

No hace falta leer primero todo el repositorio. Si tu problema es:

• estructura semántica u objetivo de conformidad: empieza por references/wcag-guidelines.md
• comportamiento de widgets o roles: abre references/aria-patterns.md
• objetivos táctiles o tecnologías de asistencia móvil: abre references/mobile-accessibility.md

Esa ruta de lectura focalizada hace más rápida la accessibility-compliance install y su adopción.

Mejora la confianza pidiendo justificación

Pide a la skill que explique por qué importa cada corrección para usuarios de teclado, usuarios de lectores de pantalla, personas con baja visión o personas con sensibilidad al movimiento. Esto ayuda a detectar correcciones superficiales y facilita que los equipos justifiquen el trabajo de implementación durante las revisiones.

La mejor forma de obtener una salida lista para producción

Para obtener el mayor valor de accessibility-compliance usage, pide todo lo siguiente en una sola pasada:

• hallazgos priorizados
• código corregido
• justificación
• checklist de verificación manual
• riesgos o supuestos pendientes

Ese paquete es lo que la mayoría de equipos realmente necesita para pasar de “deberíamos mejorar la accesibilidad” a “podemos implementar y verificar esto ahora”.