Hideki-Kobayashi/apply-digital-agency-design-system

Aplicar el Sistema de Diseño de la Agencia Digital

A partir de la instantánea oficial aprobada en Markdown, seleccionar y aplicar solo las evidencias necesarias para la solicitud. Separar el trabajo normal de la verificación de actualizaciones oficiales, y no activar candidatos de actualización sin la aprobación del usuario. En adelante, <skill-root> se reemplazará por la ruta absoluta del directorio donde se encuentra este SKILL.md. En adelante, <python> se reemplazará por el comando que pueda ejecutar Python 3.10 o superior. En macOS y Linux se usa normalmente python3, en Windows normalmente py -3.

Límites de la información

• references/source-manifest.json indica active_snapshot.path, que se usará como la instantánea activa para el trabajo normal.
• El source-index.json de la instantánea activa, references/task-index.md y references/foundation-map.md son materiales derivados. El significado oficial se confirma en el Markdown correspondiente dentro de la instantánea activa.
• Los Markdown oficiales son reconstrucciones para referencia de la IA, no un sustituto completo del sitio oficial. Si la documentación local no tiene la descripción necesaria, se reportará como un elemento no confirmado.
• Este Skill no es oficial, y no representa provisión, aprobación, afiliación o recomendación por parte de la Agencia Digital.
• Los valores actuales de un proyecto existente se confirman a partir de variables CSS, configuración de tema, estilos comunes y componentes comunes. No se copian dentro del Skill.
• Creación, modificación y revisión son categorías de permiso de operación. Nueva creación, modificación existente y componentes individuales son categorías de selección de documentación, y no deben confundirse.

Juicio de vencimiento de actualización al inicio

Al inicio, ejecutar el siguiente comando. Este comando solo lee archivos locales, no se conecta a la red.

<python> <skill-root>/scripts/manage_upstream.py status

El status de la salida se guarda como status_at_start y se mantiene durante toda la solicitud.

• fresh: No se emite aviso de actualización, se continúa con el trabajo normal.
• due, never_checked, unknown: No se detiene el trabajo normal, se vuelve a verificar el estado al finalizar.
• Si el usuario indica explícitamente desde el principio "verifique la última versión", etc.: Se trata la solicitud explícita como consentimiento para verificación externa y se procede al procedimiento de mantenimiento.

El plazo se determina a partir de last_successful_check_at con 30 días. La fecha y hora de la propuesta, la fecha y hora de fallo, o la fecha de próxima verificación derivada no son el punto de partida del plazo.

Trabajo normal

1. Clasificar la solicitud en creación, modificación o revisión, y determinar el alcance de operación permitido.
2. Confirmar la configuración técnica del objetivo, los estilos existentes, las restricciones de marca y la estructura de pantalla.
3. Determinar la ruta de selección de documentación con el siguiente orden de prioridad.
   • Si el objetivo se limita a un único componente de UI y su estado, se trata como componente individual.
   • Si ya existen estilos comunes, se trata como modificación existente.
   • En cualquier otro caso, se trata como nueva creación.
4. Seleccionar el documento objetivo de references/task-index.md. Si no corresponde, buscar en la instantánea activa con el siguiente comando.

<python> <skill-root>/scripts/search_guidance.py \
  --query '<términos de búsqueda separados por espacios>' \
  --manifest-file <skill-root>/references/source-manifest.json

5. Usar references/foundation-map.md según la ruta de selección de documentación.
   • Nueva creación: Adoptar las 8 categorías, dividir en aplicable, no aplicable y pendiente, y leer los Markdown oficiales de las categorías donde se determinen valores.
   • Modificación existente: Investigar primero los valores existentes, leer solo las categorías afectadas, y dividir en mantenimiento, migración y desviación intencional.
   • Componente individual: Leer solo los estándares comunes existentes, el componente objetivo y el diseño base afectado. No redefinir valores comunes dentro del componente.
6. Distinguir entre opciones oficiales, valores predeterminados, ejemplos, principios, requisitos y valores fijos, y asociar los valores adoptados con su justificación.
7. Implementar con la configuración técnica existente. No aplicar los ejemplos oficiales como valores fijos uniformes, ni relajar los requisitos oficiales como preferencia visual.
8. Según el objetivo, verificar múltiples anchos de pantalla, operación por teclado, foco, cambios de estado, zoom y reflujo.
9. En las solicitudes de revisión, no modificar archivos, solo devolver observaciones con justificación.

Informe de finalización del trabajo normal

Informar de manera concisa lo siguiente.

• Versión de referencia: ID de la instantánea en source-manifest.json, versión del sistema de diseño de la Agencia Digital, fecha de publicación de los Markdown.
• Alcance de revisión: Documentos oficiales leídos y verificaciones realizadas.
• Elementos no confirmados: Ámbitos no verificados, como dispositivos reales, tecnología de asistencia, páginas actuales externas, etc.
• Desviaciones: Contenido cambiado respecto a ejemplos o recomendaciones oficiales por razones específicas del proyecto.

Solo si el estado al inicio era due, never_checked o unknown, volver a ejecutar status justo antes del informe. Si no se ha vuelto fresh por otro proceso, al final del informe final se propone una sola vez la verificación de actualización.

Han pasado más de 30 días desde la última verificación oficial de actualización. El trabajo actual se completó con la versión aprobada vigente. ¿Desea también realizar una verificación de actualización?

En caso de never_checked o unknown, no se determina el número de días transcurridos y se muestra la razón. La sola propuesta no realiza comunicación externa ni actualización de estado. Si el usuario rechaza, no se guarda la fecha y hora del rechazo, por lo que se seguirá proponiendo en adelante hasta que se confirme un éxito.

Verificación de actualización oficial

Solo si el usuario ha aceptado, ejecutar lo siguiente. --network-approved se añade solo después de confirmar el consentimiento del usuario. Incluso si han pasado menos de 30 días, si se desea verificar explícitamente la última versión, agregar --force.

Dejar que el backend de obtención sea el auto predeterminado. Si se encuentra ax, auto delega a ax la obtención de la página oficial, extracción de enlaces y guardado en ZIP; si no se encuentra, utiliza la biblioteca estándar de Python. ax es recomendado pero opcional, y no se condiciona la verificación de actualización a su instalación. La ruta ax verifica la URL final después de la redirección, pero no puede verificar los destinos intermedios antes de la comunicación. Si es necesario restringir de antemano los destinos de redirección, usar --fetch-backend stdlib. Si un backend elegido falla, no cambiar implícitamente a otro backend. La verificación de URL, tamaño y formato ZIP, cálculo de hash, creación de diferencias y guardado de estado se realizan en Python. Solo para fijar el método en pruebas de funcionamiento, etc., agregar --fetch-backend ax o --fetch-backend stdlib.

<python> <skill-root>/scripts/manage_upstream.py check \
  --network-approved

• unchanged: Actualizar la fecha y hora de verificación exitosa, e informar el backend de obtención y que no hubo cambios.
• candidate_created o candidate_exists: Informar el backend de obtención, el ID del candidato, la fuente de obtención, el hash, y el número de adiciones, cambios y eliminaciones.
• skipped_fresh: Informar que se omitió la verificación externa por ser inferior a 30 días.
• Fracaso: Sin cambiar last_successful_check_at ni la instantánea activa, informar la fuente fallida y la razón.

El consentimiento para verificación externa no se trata como aprobación para adoptar un candidato. Incluso si se encuentra un candidato, si la verificación de la fuente oficial y el guardado del candidato se han completado, se actualiza la fecha y hora de verificación exitosa.

Obtención manual de ZIP

Solo si la obtención automática finalmente falla y check puede identificar la URL del ZIP oficial hasta guiar la obtención manual, se propone este procedimiento como último recurso. Si el fallo ocurre antes de identificar la URL, no adivinar la fuente a partir de la URL o el nombre del archivo, solo informar el fallo.

Mostrar lo siguiente al usuario.

La obtención automática del ZIP ha fallado. Puede obtenerlo manualmente desde la siguiente URL oficial:
<URL del ZIP oficial>

Guarde el ZIP en cualquier carpeta. Después de guardarlo, indique la ruta absoluta que incluya el nombre del archivo.
El ZIP recibido se verificará sin conexión a la red y se guardará como candidato de actualización. El cambio a la versión activa se confirmará por separado.

Cuando el usuario proporcione la ruta absoluta, ejecutar lo siguiente. Si solo se conoce una ruta relativa, confirmar la ruta absoluta antes de ejecutar.

<python> <skill-root>/scripts/manage_upstream.py import-archive \
  --archive-file '<ruta absoluta del ZIP>'

import-archive vincula el ZIP local a la URL oficial registrada en el fallo, y realiza la verificación y candidatura del tamaño normal, formato ZIP, rutas internas, conjunto de Markdown y hash sin conectarse a la red. No modifica ni elimina el ZIP original. La importación local no se trata como éxito de verificación externa, y no se actualizan last_successful_check_at ni la versión contractual verificada. Incluso si el resultado es candidate_created o candidate_exists, no se promueve automáticamente, y se procede a "Evaluación y promoción de candidatos de actualización".

Si han pasado más de 30 días desde la identificación de la URL oficial, o si el acuerdo de actualización ha cambiado, no omitir la importación y solicitar un nuevo consentimiento para verificación de actualización. Incluso si la obtención manual o la importación local fallan, no se modifican last_successful_check_at ni la instantánea activa.

Evaluación y promoción de candidatos de actualización

1. Leer candidate-manifest.json y diff-summary.json dentro del candidato.
2. Verificar el candidato con verify_snapshot.py.

La ubicación de guardado predeterminada de los candidatos es candidates dentro del directorio de estado específico del usuario.

<python> <skill-root>/scripts/verify_snapshot.py \
  --snapshot-dir <state-dir>/candidates/<ID del candidato>/snapshot \
  --index-file <state-dir>/candidates/<ID del candidato>/source-index.json

3. Leer los documentos oficiales añadidos, modificados o eliminados, y verificar el impacto en task-index.md y foundation-map.md.
4. Probar solicitudes representativas de creación, modificación y revisión con la versión anterior y la candidata.
5. Mostrar al usuario el ID del candidato, los cambios de significado, los cambios en materiales derivados y los resultados de verificación, y confirmar explícitamente la adopción.
6. Solo después de que el usuario apruebe especificando el ID del candidato, ejecutar lo siguiente.

<python> <skill-root>/scripts/manage_upstream.py promote \
  --candidate-id '<ID del candidato>' \
  --human-approved

Después de la promoción, no eliminar la instantánea anterior. La operación de promoción no cambia last_successful_check_at.

Reglas de juicio

• No usar MANIFEST.md como fuente autorizada de la lista de archivos. Escanear todos los Markdown.
• Usar source_url normalizado como ID de documento. No usar slug como ID único porque se duplica en el texto y el historial de actualizaciones.
• No crear componentes, tokens o nombres de clase no encontrados como especificación oficial.
• Si los valores existentes entran en conflicto con los requisitos oficiales, no mantener o reemplazar silenciosamente, sino mostrar el impacto y el alcance de la corrección.
• No declarar conformidad total con el sistema de diseño de la Agencia Digital o WCAG basándose únicamente en la verificación visual de la pantalla.
• Si se incluye atribución en publicaciones, leer introduction/notices/index.md de la instantánea activa.
• Guardar el estado de actualización y los candidatos en el área local específica del usuario, sin mezclarlos con los archivos de distribución del Skill. Solo si se desea cambiar la ubicación de guardado, usar la variable de entorno DADS_SKILL_STATE_DIR.