hayatosc/artefactos-html

Artefactos HTML

Entrega un archivo .html legible por humanos que se abra desde el disco y funcione sin conexión. Utiliza el adaptador de documento del Sistema de Diseño de la Agencia Digital de Japón (DADS) incluido, no una CDN ni un framework. Mantén el código fuente orientado al agente en Markdown. Este es un adaptador de documento no oficial, no una implementación completa de cada componente de DADS.

Procedimiento

1. Comprender al lector y la fuente

Identifica el tema, la audiencia, el propósito y la evidencia antes de elegir la estructura. Para planes, conserva los objetivos, la evidencia de finalización, las restricciones, los puntos de control y los riesgos. Incluye un título descriptivo, una breve orientación y la procedencia de la fuente/fecha. Añade una tabla de contenido solo cuando sea útil; no fuerces un número de secciones o un diagrama.

Explica desde cero: comienza con una situación concreta y qué hace el tema, luego introduce los nombres técnicos. Define la jerga en el primer uso, da una idea por paso y usa una imagen etiquetada solo cuando explique más claramente que la prosa. Usa analogías solo cuando su conexión y límites sean explícitos; mantén un tono adulto y directo a menos que escribas para niños. Un recién llegado debe entender qué sucede, por qué y qué hacer a continuación.

2. Construir mecánicamente — nunca reescribir el CSS

Lee build.md. Resuelve el directorio de la habilidad desde la ubicación de este archivo, no del directorio de trabajo del proyecto actual. Con Python 3.10+:

python /ruta/absoluta/hacia/html-artifacts/scripts/build.py /ruta/absoluta/hacia/salida.html --title "Tema"

El constructor lee assets/template.html, incrusta todo el contenido de assets/dads.css y assets/print.js, e inserta una Política de Seguridad de Contenido (CSP) sin conexión. Se niega a sobrescribir un archivo existente. No se necesitan descargas, instalación de paquetes, servidor, empaquetador o carpeta de activos adyacente. En este repositorio, usa su ejecutor de Python (uv run python también funciona).

3. Editar el contenido, no la base

Edita el archivo generado. Reemplaza el contenido explicativo inicial, la procedencia y la tabla de contenido; elimina las secciones innecesarias. Mantén intactos style#dads-css, script#dads-print, la CSP, el juego de caracteres, la ventana gráfica y los metadatos de only light color-scheme.

• Solo SVG en línea e imágenes raster incrustadas. Sin hoja de estilo, script, fuente, imagen, iframe, importación, fetch o dependencia de analítica remota/local. Los hipervínculos de origen ordinarios pueden apuntar a la web; etiqueta los archivos fuente locales como texto en lugar de enlaces relativos rotos.
• Usa HTML semántico y las clases/tokens incluidos. Lee dads.md para la API de clases, fuentes oficiales y adaptaciones locales. No mezcles las API data-type/data-size aguas arriba con los modificadores de este adaptador.
• Usa diagrams.md antes de agregar SVG. Dale a cada diagrama significativo un título, descripción, etiquetas y una alternativa de texto. Coloca los diagramas anchos en una región .dads-diagram-scroll etiquetada y enfocable por teclado.
• Usa fuentes de respaldo instaladas; la falta de Noto no debe ocultar texto. Haz coincidir lang con el contenido. El cuerpo es 1rem/1.7 (16px en la configuración predeterminada). Preserva el zoom y la redistribución del navegador.
• Por defecto, usa enlaces y divulgaciones nativas. Mantén las divulgaciones inicialmente open para que la impresión sin script retenga el contenido; el script incluido también abre cualquier divulgación colapsada por el lector para imprimir y la restaura después. No agregues pestañas, botones inactivos, JavaScript arbitrario o atributos de manejador de eventos.
• Mantente claro en la configuración del sistema operativo oscuro: este adaptador no tiene una paleta oscura oficial verificada. No inviertas solo el fondo de la página ni inventes un conjunto de tokens oscuros. Respeta los colores forzados y el movimiento reducido.
• Prefiere los componentes existentes. Si es esencial, coloca reglas pequeñas específicas del documento en un <style> en línea separado; las nuevas clases deben ser artifact-* y tener definiciones allí. Usa tokens conocidos, nunca los redefinas ni alteres el CSS incluido. Verifica estas reglas en el navegador; la validación estática no es un analizador CSS ni una auditoría de contraste.

4. Autoverificación final — corrige fallos antes de la entrega

Ejecuta después de la última edición:

python /ruta/absoluta/hacia/html-artifacts/scripts/check.py /ruta/absoluta/hacia/salida.html

Luego verifica el archivo real en un navegador, con la red deshabilitada cuando sea posible:

1. Contenido: la prosa inicial/placeholders han desaparecido; la evidencia solicitada, las fuentes, las fechas y las acciones siguientes permanecen. Lee las descripciones de los diagramas de forma independiente; deben transmitir el significado.
2. Sin conexión: sin solicitudes de recursos, activos fallidos, violaciones de CSP o errores de consola. Los hipervínculos de origen son navegación, no dependencias incrustadas.
3. Móvil/escritorio: inspecciona capturas de pantalla a 390px y 1280px; además, verifica la redistribución a 320px/200% de tamaño de texto. Sin desbordamiento horizontal en toda la página; solo las regiones de código/tablas/diagramas etiquetadas y enfocables pueden desplazarse. Inspecciona los glifos japoneses reales y las URL largas.
4. Teclado/estados: sigue el enlace de salto y la tabla de contenido, tabula a las regiones de desplazamiento, alterna las divulgaciones e inspecciona el foco visible y el contraste de los enlaces de botones (incluyendo visitado/desplazamiento). Sin significado solo basado en color.
5. Oscuro/impresión: emula la preferencia oscura (la página debe permanecer legible en claro), imprime con una divulgación cerrada, verifica que su cuerpo se imprima y revisa tablas/código anchos y saltos de página. Preserva el contenido sin JavaScript dejando las divulgaciones abiertas inicialmente.

El verificador exige el contrato de activos/política incluido, las clases/tokens conocidos y las reglas conservadoras de recursos sin conexión. No prueba la sintaxis CSS, el diseño, el contraste, la accesibilidad o la corrección de HTML arbitrario. Si no hay navegador disponible, di qué verificaciones visuales/interactivas quedan sin verificar; nunca afirmes capturas de pantalla solo de verificaciones estáticas.

5. Entregar

Guarda junto a la fuente o en el directorio de trabajo, nombrado según el tema (PLAN.html para un plan). Devuelve el enlace al artefacto y las limitaciones materiales, no una copia del documento o una segunda autoverificación genérica.

Para SSH/otro dispositivo, sigue remote-preview.md. Una ruta remota o xdg-open no es una entrega de visualización utilizable. Sirve solo una copia aislada, usa un túnel público solo para contenido autorizado para compartir públicamente; de lo contrario, usa reenvío SSH/control de acceso y proporciona instrucciones de limpieza. Mantén el HTML original seguro sin conexión.

Recursos

• assets/template.html, assets/dads.css, assets/print.js: fuentes incrustadas mecánicamente.
• scripts/build.py, scripts/check.py: compilación de biblioteca estándar y verificación de contrato final.
• build.md: patrones de edición y solución de problemas.
• dads.md: procedencia oficial, tokens, API de componentes del adaptador.
• diagrams.md: patrones SVG en línea legibles.
• remote-preview.md: entrega remota segura.

El enfoque de explicar desde cero está inspirado en la habilidad ELI5.