Atributos requeridos del rol ARIA
Consulte un rol ARIA y obtenga su contrato exacto: checkbox exige aria-checked, tiene 8 atributos recomendados como aria-label o aria-invalid y necesita un nombre accesible. Basado en WAI-ARIA 1.2, con los roles desconocidos rechazados. Gratis en su navegador.
- Gratis
- Funciona en su navegador
- Sin registro
- Sus datos no salen de su equipo
Ejecutar — gratis
Ejemplo resuelto
- Cargo
- checkbox
- Categoría
- widget
- Superclase
- input
- Atributos obligatorios
- aria-checked
- Cantidad obligatoria
- 1
Accessible Rich Internet Applications (ARIA) define decenas de roles para que los widgets personalizados expongan el mismo significado que los controles HTML nativos. Cada rol lleva un contrato fijo: algunos estados y propiedades son obligatorios, otros se recomiendan para un buen soporte de tecnologías de asistencia, y muchos roles exigen además un nombre accesible. Adivinar esos atributos de memoria es una causa frecuente de fallos en auditorías: falta aria-checked en un rol checkbox, se olvida aria-controls en un combobox o se publica un landmark region sin etiqueta. Esta capacidad acepta un único nombre de rol ARIA, normaliza mayúsculas y prefijos habituales, y devuelve un paquete determinista: atributos requeridos, atributos recomendados, categoría, superclase, requisitos de nombre y una descripción breve basada en WAI-ARIA 1.2.
Qué significan los atributos ARIA requeridos y recomendados
En la especificación WAI-ARIA cada rol concreto enumera Required States and Properties —atributos que el autor debe suministrar para que el rol sea válido— y Supported States and Properties que las tecnologías de asistencia esperan cuando el patrón necesita un estado más rico. Los atributos requeridos no son negociables: un rol checkbox sin aria-checked, un slider sin aria-valuenow o un combobox sin aria-controls y aria-expanded fallan las comprobaciones automáticas y confunden a los lectores de pantalla.
La respuesta también indica si el rol exige un nombre accesible y cómo puede calcularse (atributos del autor, contenido del elemento o prohibido). Roles concretos deprecados como directory siguen siendo consultables pero se marcan para que las herramientas de migración avisen sin bloquear la consulta.
Qué puede hacer con ella
Oráculos de lint de accesibilidad en CI
Con valores role extraídos del marcado o de Storybook, compruebe que todo atributo requerido está presente antes del merge; falle en roles abstractos o desconocidos.
Preguntas frecuentes
¿Qué atributos ARIA son obligatorios para un rol dado?
Envíe el nombre del rol (por ejemplo checkbox, combobox, slider).
¿Valida esta capacidad mi página HTML?
No. Solo consulta las características de la especificación para un nombre de rol. Use un auditor de accesibilidad (por ejemplo web.accessibility) para escanear el marcado en vivo.
¿Qué diferencia hay entre atributos obligatorios y recomendados?
Los obligatorios deben estar presentes para que el rol sea válido: una casilla checkbox sin aria-checked falla las revisiones automáticas y confunde a los lectores de pantalla. Los recomendados son los que esperan las tecnologías de apoyo cuando el patrón necesita más estado, como desactivado, solo lectura o mensajes de error.
¿Un rol checkbox necesita un nombre accesible?
Sí. La consulta indica que el nombre es obligatorio y que puede salir del propio contenido del elemento o del autor, por ejemplo mediante aria-label o aria-labelledby cuando el texto visible no basta.
¿Qué pasa con los roles obsoletos o abstractos?
Los roles obsoletos, como directory, se pueden seguir consultando, pero aparecen marcados para que una herramienta de migración avise sin bloquear. Los roles abstractos y los nombres desconocidos se rechazan, para que nadie añada atributos a un rol que no existe.
Herramientas relacionadas
Para desarrolladores — acceso por API
Todo lo de esta página está disponible por programación. Esta sección es para equipos que quieren integrarlo en sus sistemas; el resto puede usar la herramienta de arriba sin más.
Endpoint de API
¿Prefiere automatizarlo? Un POST autenticado crea la tarea; el resultado llega por webhook o enlace firmado. La misma capacidad también se ejecuta aquí en la web, por email y desde Telegram — y pronto también desde nuestra app.
Llámela desde su stack
curl -X POST https://api.kit.forhosting.com/web/aria-role-lookup \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"role":"checkbox"}'const res = await fetch("https://api.kit.forhosting.com/web/aria-role-lookup", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"role": "checkbox"
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/web/aria-role-lookup",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"role": "checkbox"
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/web/aria-role-lookup", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"role":"checkbox"}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"role":"checkbox"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/web/aria-role-lookup", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Ejemplo de solicitud
{
"role": "checkbox"
}Ejemplo de respuesta
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "web.aria_role_lookup",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}La API es asíncrona: la llamada devuelve un task_id al instante y el resultado llega por webhook. El polling está limitado a 1 req/s por tarea.
Precio
Precio publicado — sin tokens ni créditos inventados. Una tarea fallida no se cobra.
Límites
timeout_sec | 30 |
max_crawl_pages | 25 |
Errores
| HTTP | Código | Significado |
|---|---|---|
401 | unauthorized | API key ausente o inválida. |
402 | insufficient_balance | El saldo no cubre el precio de la tarea. |
404 | unknown_type | El tipo de tarea no existe. |
429 | rate_limited | Demasiadas peticiones. Use el webhook en vez de sondear. |
Notas técnicas
Los nombres no reconocidos y los roles abstractos fallan con invalid_input para que el cliente no invente atributos de roles inexistentes. La misma tabla pura alimenta la herramienta gratuita del navegador y la API de prepago a $0.002 por ítem correcto.
Qué significan los atributos ARIA requeridos y recomendados
Los atributos recomendados en esta API son las propiedades soportadas que los autores suelen necesitar para un comportamiento correcto de teclado y de AT: flags de selección y expansión, mínimo y máximo de valor en widgets de rango, orientación en toolbars y tablists, y ayudas de nombre como aria-label y aria-labelledby cuando el texto visible no basta.
Contrato de entrada, forma de la respuesta y errores
Pueden aparecer notes opcionales cuando un requisito es condicional: por ejemplo un separator con foco necesita aria-valuenow, aria-valuemin y aria-valuemax aunque un separator decorativo estático no. Ejemplo: el rol checkbox devuelve aria-checked como requerido y un conjunto recomendado que cubre readonly, required, disabled, etiquetado y mensajes de error. Ejemplo: el rol scrollbar devuelve las cuatro propiedades obligatorias aria-controls, aria-valuenow, aria-valuemin y aria-valuemax. Envíe un cuerpo JSON con un campo de cadena obligatorio, role, que también puede llegar bajo los alias value, name, query o aria_role. El motor recorta espacios, pasa el token a minúsculas, elimina prefijos opcionales como role= o aria-role y quita espacios o guiones bajos internos para que column header y columnheader se resuelvan igual. En caso de éxito el cuerpo repite el rol normalizado, category, superclass, description, abstract false, required_attributes y recommended_attributes como arrays de cadenas ordenados, required_count y recommended_count, name_required, name_from, deprecated y spec fijado en WAI-ARIA 1.2. Falta de role, cadena vacía, nombres desconocidos y roles abstractos lanzan invalid_input con un mensaje que nombra el problema; esos fallos no se facturan. Combine la consulta con su propia documentación de lint o design system; este endpoint no rastrea una página ni valida marcado en vivo: solo responde la pregunta de especificación para un nombre de rol cada vez.
Dónde aporta valor la consulta de atributos de rol ARIA
Las plataformas de formación y los cursos WCAG usan la ruta gratuita del navegador para que el alumnado explore checkbox frente a switch, o dialog frente a alertdialog, sin memorizar las tablas de características completas. Fije en sus pruebas los arrays ordenados devueltos, documente el rechazo de roles abstractos para autores que copian nombres de taxonomía por error, y obtendrá un contrato estable para guías de estilo, herramientas MCP y validadores en el borde sin montar un motor de accesibilidad completo. Los linters de accesibilidad y los plugins de CI llaman a la API como oráculo: dado el role hallado en un nodo, obtienen los atributos requeridos y fallan el build si falta alguno. Como la implementación es parse de nivel A con modelo de coste analítico, cada llamada correcta cuesta el precio base publicado $0.002, se ejecuta sin red en el isolate del worker y no depende de recuperar el sitio del W3C.
Casos de integración
Documentación de design system
Genere tablas ARIA por componente a partir del string role para que los ingenieros vean atributos requeridos y recomendados junto a la API de React o Web Components.
Formación y talleres WCAG
Permita que el alumnado consulte checkbox, combobox y region de forma interactiva y compare las reglas name_required sin memorizar las tablas WAI-ARIA completas.
Preguntas técnicas
¿Qué ocurre si el nombre del rol es desconocido?
La tarea falla con invalid_input y un mensaje de que el rol no se reconoce. Los roles abstractos como widget o landmark también se rechazan porque los autores no deben usarlos.
¿La consulta distingue mayúsculas y minúsculas?
No. Los nombres de rol se normalizan a minúsculas; se eliminan prefijos opcionales como role= y se quitan espacios o guiones bajos dentro del token.
¿Cuánto cuesta la consulta de atributos de rol ARIA?
La herramienta del navegador es gratuita. Las peticiones a la API usan saldo prepago del KIT a $0.002 por llamada correcta; la entrada inválida no se factura.