Requisição 135 — Controle de Animações do Sistema Operacional via CLI (c2f motion:on|off|status) para Validação de prefers-reduced-motion

• Status do intake: ready-for-intake

• Data: 2026-08-26

• Origem: especificação Frente 1 de conn2flow-ai-workspace/sdd/human-requests/req-023.md

• Classificação: cli, accessibility, animations, testing, developer-experience

• Batch candidato: BATCH-137

Esta especificação define os requisitos para implementar no CLI c2f os comandos de gerenciamento de efeitos visuais e animações do sistema operacional (c2f motion:status, c2f motion:on, c2f motion:off, c2f motion:toggle), permitindo que desenvolvedores e agentes de IA validem componentes e páginas nos dois estados de acessibilidade (prefers-reduced-motion: reduce e no-preference) de forma automatizada, determinística e reversível.

1. Contexto e Motivação Técnica

• O Problema no Teste de CSS/Acessibilidade:

  • O Chrome e outros navegadores determinam a media query @media (prefers-reduced-motion) a partir da configuração de acessibilidade do sistema operacional (no Windows: Acessibilidade > Efeitos visuais > Efeitos de animação / SPI_GETCLIENTAREAANIMATION).

  • As ferramentas de desenvolvedor do Chrome só oferecem emulação restritiva (forçar reduce), não permitindo forçar no-preference quando o sistema do operador está com animações desativadas.

  • Para validar comportamentos de UI que se adaptam à acessibilidade (como indicadores de digitação, spinners de loading e efeitos de revelação progressiva), o agente precisa alternar o estado do sistema, inspecionar a página via c2f page:inspect e restaurar o estado original.

2. Comandos CLI Requeridos (c2f motion:*)

• Nomenclatura e Assinatura:

  • c2f motion:status (aliases: c2f motion:get, c2f anim:status): Consulta e exibe o estado atual no terminal (ON - prefers-reduced-motion: no-preference ou OFF - prefers-reduced-motion: reduce).

  • c2f motion:on (alias: c2f anim:on): Ativa os efeitos de animação do sistema.

  • c2f motion:off (alias: c2f anim:off): Desativa os efeitos de animação do sistema.

  • c2f motion:toggle (alias: c2f anim:toggle): Alterna entre ligado e desligado.

3. Arquitetura de Implementação por Sistema Operacional

3.1. Windows (PowerShell / P/Invoke user32.dll)

• Utilizar a API nativa do Windows via SystemParametersInfoW:

  • Leitura: SPI_GETCLIENTAREAANIMATION (0x1042).

  • Escrita: SPI_SETCLIENTAREAANIMATION (0x1043) com valor 1 (on) ou 0 (off) e flag SPIF_UPDATEINIFILE | SPIF_SENDCHANGE (3) para persistir e notificar janelas ativas.

• Cuidados Mandatórios de Segurança e Integridade:

  1. Mexer estritamente em SPI_SETCLIENTAREAANIMATION. É proibido alterar MinAnimate ou chaves de registro globais (UserPreferencesMask), preservando as preferências de janela do operador.

  2. Declarar explicitamente EntryPoint="SystemParametersInfoW" no P/Invoke do C# para evitar EntryPointNotFoundException.

  3. Exibir instrução informativa lembrando que o navegador pode exigir recarregamento da aba (F5) para reler a media query.

3.2. Linux e macOS

• Linux (GNOME/Desktop): Executar gsettings set org.gnome.desktop.interface enable-animations true|false (e get correspondente).

• macOS: Executar defaults write com.apple.universalaccess reduceMotion -bool true|false.

• Outros Ambientes: Caso a plataforma não seja suportada, emitir mensagem clara (Platform not supported for motion control) retornando código 0 de forma informativa.

4. Critérios de Aceitação

1. Sintaxe e Lint: php -l 100% limpo em MotionCommand.php e arquivos auxiliares.

2. Execução Funcional:

   • c2f motion:status reporta o estado real do SO.

   • c2f motion:on e c2f motion:off alternam o estado de forma não-destrutiva e sem impactar animações de janelas do SO (MinAnimate).

3. Suíte PHPUnit: Testes unitários cobrindo o comando CLI, aliases e tratamento de plataformas.