Trabajar con IA

Dale LUZ a tu agente

LUZ usa HTML y CSS sin más, así que un agente de programación con IA puede escribirlo si conoce los nombres de clase disponibles. Pega este prompt en tu agente.

Indica al agente los archivos que aparecen abajo y le pide que ejecute el comprobador sobre lo que ha escrito. En Lo que no hace se explica qué no comprueba.

Use LUZ for the markup. Read https://nandovejer.github.io/luz/llms.txt first and use only the classes in each package's classes.json. After you write HTML or CSS, run `npx @luz-ds/check@0.3.0` on the files and fix every finding before you answer.

Empezar un sitio

Para un sitio nuevo, o para pasar uno a LUZ, dale a un LLM el prompt largo. Te pregunta por el proyecto en rondas cortas, te enseña el plan y no escribe nada hasta que dices "go".

Abrir el prompt

Para un tipo de sitio concreto, su página tiene un prompt hecho para él y las recetas de sus partes: una landing page, un blog o un periódico, una aplicación web o un sitio de documentación.

Qué puede leer un agente

La compilación de este sitio genera cada archivo a partir de las páginas que estás leyendo, así que tanto un agente como una persona obtienen la misma información. Dale al agente la URL de llms.txt: ahí se enumeran los demás archivos.

Comprueba lo que ha escrito un agente

npx @luz-ds/check@0.3.0 lee sin conexión el HTML y el CSS de un proyecto e indica qué clases, elementos, orden de carga y tokens de color de LUZ son incorrectos. Lee archivos, pero no escribe nada.

Necesita Node 20 o posterior.

npx @luz-ds/check@0.3.0
npx @luz-ds/check@0.3.0 index.html css/site.css
npx @luz-ds/check@0.3.0 src --json

Indica npx @luz-ds/check@0.3.0 y el ámbito. Una ruta puede ser un archivo, una carpeta (la lectura es recursiva: .html, .htm y .css) o un patrón glob entre comillas, como "src/**/*.html".

Si no indicas ninguna ruta, lee la carpeta actual.

Un archivo luz-check.json en la carpeta desde la que ejecutas el comando configura ignore, rules, themes y strict. Desde ahí puedes desactivar una regla que avisa; una regla bloqueante solo se silencia con ignore. El resumen indica cuántos hallazgos se han ignorado y cuántas reglas están desactivadas.

Códigos de salida

Qué muestra

Una línea por cada hallazgo, en el orden de los archivos y las líneas: un símbolo (✗ bloquea, ! avisa), la ubicación, la regla y una frase que explica qué está mal y qué hacer. Después de un hallazgo sobre un token de color aparecen las líneas donde se definieron los colores.

La última línea cuenta los hallazgos encontrados en los archivos que ha leído.

✗ index.html:14:8 class/unknown  .luz-btn-primary is not a LUZ class; the closest is .luz-btn--primary
✗ index.html:22:5 load/package-missing  <luz-announcement> is in @luz-ds/catalog/components/announcement.css; add it after core
! site.css:8:3 css/literal-colour  color is set to #1a5fb4; use a token, such as var(--luz-brand-fill)
✗ theme.css:3:3 theme/contrast  light: --luz-text-secondary on surface-page is 2.8:1, needs 4.5:1 (text); change one of the two
    --luz-text-secondary: #999999 is set in theme.css:3
✗ 3 blocking and 1 warning in 3 files (manifests: @luz-ds/core 0.1.0 from node_modules)

La parte (manifests: …) indica con qué versión de LUZ se han comprobado los nombres y de dónde procede: de tu node_modules o de la copia incluida con el comando.

El informe JSON

--json muestra un objeto con estos campos. Si un campo no aparece en esta tabla, no forma parte del informe.

Lo mismo ocurre con el texto y con JSON: las rutas y los nombres que contienen caracteres no habituales se escriben con escapes, y el comando nunca cita el contenido de tus archivos.

Qué bloquea y sobre qué avisa check

Cada regla tiene un id, como class/unknown, que aparece en todos los hallazgos. Una regla bloqueante hace que el código de salida sea 1.

Una regla que avisa no lo hace, salvo que pases --strict. Las dos tablas se generan a partir de la lista de reglas del comando.

Catalog 0.3 cambió el nombre de sus clases, elementos, archivos y módulos, y los nombres antiguos no hacen nada. names/renamed encuentra una clase, una etiqueta, un enlace a un archivo de componente o un módulo con el nombre antiguo, y da el nombre nuevo. No dice nada en una página que enlaza catalog 0.0 a 0.2, donde los nombres antiguos son los correctos.

El revisor de accesibilidad

El mismo paquete muestra una definición de agente para un asistente de programación con IA: un revisor que lee el código fuente de una página y ofrece recomendaciones de accesibilidad. Cópiala en tu proyecto.

npx @luz-ds/check@0.3.0 agent > .claude/agents/luz-accessibility-reviewer.md

• Sobrescribe archivos. El operador > sustituye un archivo existente. Si lo has editado, usa otra ruta o guarda antes tu copia en el control de versiones.
• Es de solo lectura. Tiene tres herramientas, Read, Grep y Glob: lee, busca y enumera archivos, pero no escribe nada. Solo lectura no significa que sea inofensivo, porque Read no limita las rutas. Lee el archivo antes de usarlo y revisa cualquier cambio como harías con el código.
• Ofrece recomendaciones. Revisa el código fuente según el nivel AA de WCAG 2.2 y EN 301 549, y etiqueta cada hallazgo como confirmado en el código fuente o como algo que requiere un navegador o tecnología de asistencia. Sus hallazgos son sugerencias basadas en la lectura del código, no resultados de pruebas.
• No usa tecnología de asistencia. No abre páginas ni ejecuta scripts, y no observa cómo se representa una página, así que no sustituye una prueba con teclado y lector de pantalla.

El archivo también está en el paquete como @luz-ds/check/agents/accessibility.md, para que un paso de compilación lo copie.

Lo que no hace

Una ejecución sin hallazgos indica lo que el comprobador no ha encontrado en los archivos que ha leído. No es una prueba de la página.

• No ejecuta un navegador. Lee archivos, así que no detecta nada que dependa de cómo se representa una página, como la maquetación, el orden del foco o los colores que calcula el navegador.
• Solo mide el contraste de tus tokens. Mide los colores --luz-* que defines en tu propio archivo de tokens de color. No compara los colores escritos directamente en una regla con ningún otro. En Comprobación del contraste se explica cómo lee los pares.
• No detecta las clases creadas en tiempo de ejecución. Un nombre construido en un script, como "luz-" + name, o escrito por una plantilla, no está en el archivo, así que no se comprueba.
• No comprueba nombres, etiquetas, texto alternativo, encabezados ni el idioma. No analiza si un botón tiene nombre, si una imagen tiene una alternativa útil, si los encabezados están ordenados ni si la página tiene un idioma. Una ejecución sin hallazgos no dice nada sobre estos aspectos.
• No sustituye las pruebas con lector de pantalla. Ni el comando ni el revisor utilizan tecnología de asistencia. Lo que no se ha probado se enumera en la declaración de accesibilidad.
• No accede a la red. Se ejecuta sin conexión, con los datos de tu node_modules o de su propio paquete.
• El descubrimiento mediante llms.txt se hace con un enlace. Este sitio no está en la raíz de un host, así que el agente no encuentra el archivo por sí solo: dale la URL, como hace el prompt anterior.
• El código de salida 0 no es un resultado de accesibilidad. Indica que ninguna de las reglas anteriores bloquea los archivos leídos.
• Los mensajes están en inglés. No se traducen, sea cual sea el idioma de la página.