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

Aplicar o Design System da Agência Digital Japonesa

A partir do snapshot aprovado do Markdown oficial, selecione apenas a justificativa necessária para a solicitação e aplique-a. Separe o trabalho normal da verificação de atualizações oficiais e não ative candidatos a atualização sem a aprovação do usuário. Doravante, <skill-root> deve ser substituído pelo caminho absoluto do diretório onde este SKILL.md está localizado. Doravante, <python> deve ser substituído pelo comando capaz de executar Python 3.10 ou superior. No macOS e Linux, normalmente use python3; no Windows, normalmente use py -3.

Limites das Informações

• O active_snapshot.path indicado em references/source-manifest.json é o snapshot válido a ser usado no trabalho normal.
• O source-index.json do snapshot válido, references/task-index.md e references/foundation-map.md são materiais derivados. Seu significado oficial deve ser verificado no Markdown correspondente dentro do snapshot válido.
• O Markdown oficial é uma reconstrução para referência de IA e não substitui completamente o site oficial. Se a descrição necessária não estiver nos materiais locais, relate como item não verificado.
• Este Skill não é oficial e não representa fornecimento, aprovação, afiliação ou recomendação pela Agência Digital Japonesa.
• Os valores atuais de um projeto existente devem ser verificados a partir de variáveis CSS, configurações de tema, estilos comuns e componentes comuns. Não os duplique dentro do Skill.
• Criação, modificação e revisão são classificações de permissão de operação. Novo, reforma existente e componente individual são classificações de seleção de materiais e não devem ser confundidos.

Determinação de Vencimento da Atualização na Inicialização

Execute o seguinte comando primeiro. Este comando lê apenas arquivos locais e não se conecta à rede.

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

Mantenha o status da saída como status_at_start durante aquela solicitação.

• fresh: Não exiba aviso de atualização e continue o trabalho normal.
• due, never_checked, unknown: Não pare o trabalho normal, mas verifique novamente o status ao final.
• Se o usuário solicitar explicitamente desde o início, como "Verifique a versão mais recente": trate a solicitação explícita como consentimento para verificação externa e prossiga para o procedimento de manutenção.

O prazo é determinado em 30 dias a partir de last_successful_check_at. A data da proposta, a data da falha ou a próxima data de verificação derivada não são o ponto de partida do prazo.

Trabalho Normal

1. Classifique a solicitação em criação, modificação ou revisão e determine o escopo de operação permitido.
2. Confirme a configuração técnica alvo, estilos existentes, restrições de marca e estrutura de tela.
3. Decida a rota de seleção de materiais na seguinte ordem de prioridade.
   • Se o alvo for um único componente de UI e seu estado, trate como componente individual.
   • Se existir um estilo comum, trate como reforma existente.
   • Caso contrário, trate como nova criação.
4. Selecione o documento alvo de references/task-index.md. Se não for aplicável, pesquise o snapshot válido com o seguinte comando.

<python> <skill-root>/scripts/search_guidance.py \
  --query '<termos de pesquisa separados por espaço>' \
  --manifest-file <skill-root>/references/source-manifest.json

5. Use references/foundation-map.md de acordo com a rota de seleção de materiais.
   • Nova criação: Divida as 8 categorias em adotadas, não aplicáveis e pendentes; leia o Markdown oficial da categoria que determina os valores.
   • Reforma existente: Primeiro investigue os valores existentes, leia apenas as categorias afetadas e divida em manter, migrar ou desvio intencional.
   • Componente individual: Leia apenas os padrões comuns existentes, o componente alvo e o design básico afetado. Não redefina valores comuns dentro do componente.
6. Distinga entre opções oficiais, valores padrão, exemplos, princípios, requisitos e valores fixos; correlacione o valor adotado com sua justificativa.
7. Implemente com a configuração técnica existente. Não aplique exemplos oficiais como valores fixos uniformes e não afrouxe requisitos oficiais como preferências visuais.
8. Dependendo do alvo, verifique larguras de tela múltiplas, operação por teclado, foco, mudanças de estado, zoom e reflow.
9. Em solicitações de revisão, não altere arquivos; retorne apenas apontamentos com justificativas.

Relatório de Conclusão do Trabalho Normal

Relate de forma concisa o seguinte:

• Versão de referência: ID do snapshot em source-manifest.json, versão do Design System da Agência Digital Japonesa, data de publicação do Markdown.
• Escopo verificado: Documentos oficiais lidos e verificações realizadas.
• Itens não verificados: Itens não verificados, como dispositivos reais, tecnologias assistivas ou páginas atuais externas.
• Desvios: Conteúdo alterado em relação ao exemplo oficial ou recomendação por motivos específicos do projeto.

Apenas se o status na inicialização era due, never_checked ou unknown, reexecute o status imediatamente antes do relatório. Se não se tornar fresh devido a outro processamento, proponha uma verificação de atualização uma vez no final do relatório final.

Passaram-se mais de 30 dias desde a última verificação de atualização oficial. Este trabalho foi concluído com a versão atual aprovada. Deseja também realizar uma verificação de atualização?

Para never_checked ou unknown, não afirme o número de dias decorridos, mas indique o motivo. Apenas a proposta não realiza comunicação externa nem atualização de estado. Mesmo que o usuário recuse, a data/hora da recusa não é salva, portanto, a proposta continuará nas próximas vezes até que uma verificação bem-sucedida ocorra.

Verificação de Atualização Oficial

Execute o seguinte somente se o usuário concordar. Anexe --network-approved somente após confirmar o consentimento do usuário. Adicione --force se for verificar explicitamente a versão mais recente mesmo com menos de 30 dias.

Deixe o backend de obtenção para auto (padrão). auto delega a obtenção de páginas oficiais, extração de links e salvamento de ZIP para ax se encontrado; caso contrário, usa a biblioteca padrão do Python. ax é recomendado, mas opcional, e sua instalação não é um pré-requisito para a verificação de atualização. A rota ax verifica a URL final após o redirecionamento, mas não pode verificar destinos intermediários antes da comunicação. Se for necessário restringir previamente os destinos de redirecionamento, use --fetch-backend stdlib. Se o backend escolhido falhar, não mude silenciosamente para outro backend. A verificação de URL, tamanho e formato ZIP, cálculo de hash, criação de diff e salvamento de estado após a obtenção são feitos em Python. Adicione --fetch-backend ax ou --fetch-backend stdlib apenas para fixar o método em testes, etc.

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

• unchanged: Atualize a data/hora da verificação bem-sucedida e relate o backend de obtenção e que não houve alterações.
• candidate_created ou candidate_exists: Relate o backend de obtenção, ID do candidato, origem, hash, número de adições, alterações e exclusões.
• skipped_fresh: Relate que a verificação externa foi omitida por ter menos de 30 dias.
• Falha: Relate a falha sem alterar last_successful_check_at e o snapshot válido, indicando a origem da falha e o motivo.

Não trate o consentimento para verificação externa como aprovação para adoção do candidato. Mesmo que um candidato seja encontrado, se a verificação da fonte oficial e o salvamento do candidato estiverem concluídos, atualize a data/hora da verificação bem-sucedida.

Obtenção Manual do ZIP

Apenas se a obtenção automática falhar eventualmente e check conseguir identificar a URL do ZIP oficial e orientar a obtenção manual, proponha este procedimento como último recurso. Se falhar antes de identificar a URL, não adivinhe a origem pelo nome do arquivo ou URL; apenas relate a falha.

Mostre o seguinte ao usuário:

A obtenção automática do ZIP falhou. Você pode obtê-lo manualmente a partir da seguinte URL oficial:
<URL do ZIP oficial>

Salve o ZIP em qualquer pasta. Após salvar, informe o caminho absoluto, incluindo o nome do arquivo.
O ZIP recebido será verificado sem conexão de rede e salvo como candidato a atualização. A ativação como versão válida será confirmada separadamente.

Quando receber o caminho absoluto do usuário, execute o seguinte. Se apenas um caminho relativo for fornecido, confirme o caminho absoluto antes de executar.

<python> <skill-root>/scripts/manage_upstream.py import-archive \
  --archive-file '<caminho absoluto do ZIP>'

import-archive vincula o ZIP local à URL oficial registrada na falha, realiza verificação de tamanho normal, formato ZIP, caminhos internos, conjunto de Markdown e hash sem conexão de rede e cria um candidato. Não modifica nem exclui o ZIP original. A importação local não é tratada como sucesso de verificação externa; não atualiza last_successful_check_at nem a versão contratada verificada. Mesmo que o resultado seja candidate_created ou candidate_exists, não promova automaticamente; prossiga para "Avaliação e Promoção de Candidatos a Atualização".

Se mais de 30 dias se passaram desde a identificação da URL oficial, ou se o contrato de atualização mudou, não contorne a importação; solicite novo consentimento para verificação de atualização. Mesmo que a obtenção manual ou a importação local falhem, não altere last_successful_check_at nem o snapshot válido.

Avaliação e Promoção de Candidatos a Atualização

1. Leia candidate-manifest.json e diff-summary.json dentro do candidato.
2. Verifique o candidato com verify_snapshot.py.

O diretório de salvamento padrão dos candidatos é candidates dentro do diretório de estado específico do usuário.

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

3. Leia os documentos oficiais adicionados, alterados e excluídos e verifique o impacto em task-index.md e foundation-map.md.
4. Teste solicitações representativas de criação, reforma e revisão com a versão antiga e a versão candidata.
5. Apresente ao usuário o ID do candidato, as mudanças de significado, as alterações nos materiais derivados e os resultados da verificação; confirme explicitamente a adoção.
6. Somente após o usuário aprovar especificando o ID do candidato, execute o seguinte.

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

Não exclua o snapshot anterior após a promoção. A operação de promoção não altera last_successful_check_at.

Regras de Decisão

• Não use MANIFEST.md como lista de arquivos oficial. Varra todos os Markdown.
• Use o source_url normalizado como ID do documento. slug duplica no texto e no histórico de atualizações; portanto, não o use como ID único.
• Não crie componentes, tokens ou nomes de classe que não existem como especificações oficiais.
• Se um valor existente colidir com um requisito oficial, não mantenha ou substitua silenciosamente; indique o impacto e o escopo da correção.
• Não declare conformidade total com o Design System da Agência Digital Japonesa ou WCAG baseando-se apenas em inspeção visual.
• Se for necessário citar a fonte em materiais públicos, leia introduction/notices/index.md do snapshot válido.
• Salve o estado de atualização e os candidatos em uma área local específica do usuário; não os misture com os arquivos de distribuição do Skill. Use a variável de ambiente DADS_SKILL_STATE_DIR apenas para alterar o local de salvamento.