Motion Lexicon

O que Motion Lexicon faz?

Motion Lexicon é um sistema de design para movimento de produto. Ele conecta duas coleções equivalentes: as Primitivas de Movimento descrevem um comportamento preciso; os Componentes transformam um ou mais comportamentos em uma interação de produto completa e pronta para cópia. A composição de página posiciona essas interações dentro de uma superfície de produto coerente.

Projete a partir do evento do produto do usuário. Produza código apenas quando ele suportar uma mudança de estado clara, um ator focado e uma entrega acessível.

Escolha um modo

Sinal na solicitação	Modo	Entregável
Uma página completa, tela, landing page, dashboard ou superfície de configurações	Construir Página	Plano de página, composição exata do Registry, página funcional e evidência de aceitação
Uma sensação, termo ou pergunta "qual animação"	Recomendar	Candidatos ranqueados e uma recomendação
Um workflow, transição ou cena de várias etapas	Compor	Blueprint de Movimento e plano de batidas
Uma solicitação de código de produção ou adaptação de framework	Implementar	HTML, CSS, JS portáteis ou código do framework solicitado
Código existente, uma gravação ou um relatório de jank	Revisar	Diagnóstico priorizado e correções concretas
Um novo padrão, exemplo ou adição proposta à biblioteca	Contribuir	Registro candidato pronto para revisão do mantenedor

Aplique a prioridade do modo de forma determinística: uma página completa ou superfície multirregião usa Construir Página; uma solicitação explícita de código ou implementação de framework de uma interação usa Implementar; uma solicitação apenas de um plano de design, plano de batidas ou Blueprint usa Compor. Implementar pode criar um Blueprint internamente e ainda entrega o formato executável que o usuário solicitou. Uma solicitação de Revisão pode retornar um Blueprint revisado quando a interação atual precisar de uma mudança maior.

Inicie toda solicitação

1. Preserve o idioma do usuário. Use Chinês para solicitações em Chinês e Inglês para solicitações em Inglês.
2. Identifique o trabalho do produto, a ação principal, o estado visível ao usuário antes e depois dela, o ator principal e a sensação pretendida.
3. Use a tabela modo × referência abaixo. Carregue apenas os arquivos selecionados para a tarefa atual.
4. Carregue interior-principles.md quando a solicitação precisar de profundidade material, fisicalidade ou o perfil visual Interior.
5. Declare as suposições brevemente quando a solicitação deixar o contexto do produto em aberto. Faça uma pergunta focada apenas quando uma restrição ausente mudar o design.
6. Mantenha um ator visual primário e no máximo dois atores de suporte em uma batida. Dê a cada ator um tipo semântico: gatilho, herói, status, registro ou ambiente. Dê a cada batida um propósito de produto: orientar, confirmar, preservar continuidade, revelar ou recuperar.
7. Inclua um plano de movimento reduzido e comportamento de teclado/foco em toda interação composta, implementada ou revisada.
8. Para uma solicitação de página, inspecione o projeto hospedeiro antes de escolher uma stack. Preserve seu roteamento, sistema de componentes, tokens de design e idioma de conteúdo. Use React e TypeScript para uma página greenfield, a menos que o usuário solicite outra stack.

Roteamento modo × referência

Modo ou tarefa	Ler	Adicionar apenas quando relevante
Construir Página	page-composition.md, page-system.md e components.md	motion-lexicon-page.css quando o hospedeiro não tem um sistema visual estabelecido; uma referência de momento ou primitiva para a mudança de estado primária da página
Recomendar um componente publicado	components.md	Uma família de primitivas abaixo quando o usuário perguntar como o movimento funciona
Recomendar um comportamento	motion-language.md	entrances, feedback, transitions ou sequencing
Compor um Momento de Produto	composition.md e contract.md	feedback moment, choice moment, change moment ou workflow moment
Implementar	implementation-css.md	contract.md ao consumir ou produzir um Blueprint; components.md para um componente publicado exato
Revisar	review-rubric.md	A referência de primitiva ou momento que corresponde ao comportamento observado
Contribuir	contribution.md e candidate-template.md	contract.md para o Blueprint necessário e components.md para descartar um componente existente

Linguagem de movimento

Use o perfil informado pelo Interior em toda a habilidade:

• Modele um estado de produto real com uma borda (bezel), um painel elevado e um poço rebaixado quando a profundidade material ajudar na orientação.
• Inicie o movimento a partir de um evento: um pressionamento, seleção, mudança de rota, atualização de status ou manipulação direta.
• Reserve espaço para mudanças de estado para que rótulos, botões e registros mantenham sua geometria.
• Use movimento de chegada para novo contexto: cubic-bezier(.23, 1, .32, 1) em aproximadamente 200–280 ms. Use movimento de saída para contexto removido: cubic-bezier(.23, 1, .32, 1) em aproximadamente 110–180 ms.
• Use transform e opacidade para o trabalho em movimento. Use transições curtas de cor ou foco quando o feedback precisar de uma resposta imediata.
• Permita que uma segunda ação do usuário interrompa, reverta ou estabilize a primeira ação.
• Em movimento reduzido, preserve estado, hierarquia, foco e feedback por meio de um estado estático ou transição curta de opacidade.

Leia as regras detalhadas em interior-principles.md.

Construir Página

Construa uma superfície de produto completa e executável no projeto do usuário. Leia page-composition.md, page-system.md e components.md antes de planejar a página.

1. Inspecione o repositório alvo, framework, rotas, tokens existentes e dependências instaladas. Reutilize o sistema hospedeiro onde ele for coerente.
2. Antes de editar qualquer arquivo, produza a tabela de Inspeção do Hospedeiro e o Plano de Página compacto mostrados abaixo. Inclua o trabalho e o arquétipo da página, cada região principal, o ID exato do componente publicado ou none, o limite de estado primário e as decisões de responsividade e tema. Cada valor da Inspeção do Hospedeiro cita o caminho do arquivo inspecionado. Uma intenção de implementação em prosa não satisfaz esta etapa.
3. Use a fonte em https://motion-lexicon.pages.dev/r/<id>.json para um componente publicado. Leia seus files, dependencies e runtime antes de editar. Instale a fonte e as dependências entregues; adapte apenas suas props, rótulos, dados, callbacks e posicionamento no hospedeiro. Não regere uma aproximação do mesmo componente.
4. Complete a etapa de integração do Registry antes de selecionar um ID: toda fonte atual do Registry usa classes utilitárias Tailwind. Confirme que o hospedeiro já compila Tailwind, ou adicione sua configuração Tailwind suportada quando alterar a toolchain do hospedeiro estiver no escopo. Se essa configuração não puder ser adicionada, selecione none para a região e construa UI semântica simples; nunca cole silenciosamente uma reimplementação CSS de um componente do Registry. Registre a URL JSON, arquivo alvo, lista de dependências e qualquer runtime necessário no Plano de Página.
5. Audite o nó interativo renderizado após a integração. O padrão da página é de pelo menos 44 por 44 px CSS mesmo quando a altura visual padrão de um componente do Registry for menor. Passe uma classe do hospedeiro por meio de uma prop className documentada e defina min-width e min-height nesse nó. Se a fonte não oferecer um hook de estilo seguro, escolha um componente adequado que ofereça ou deixe a região simples.
6. Dê à página uma superfície de trabalho dominante, um momento de movimento primário e no máximo dois momentos de movimento de suporte. Mantenha o conteúdo estático calmo.
7. Use o sistema de design do hospedeiro. Para uma superfície greenfield, copie e adapte motion-lexicon-page.css, depois aplique a hierarquia exata e as regras de responsividade de page-system.md.
8. Entregue a rota ou página inteira, incluindo conteúdo realista, estados de carregamento, vazio, sucesso, falha e recuperação que pertençam ao seu trabalho.
9. Verifique os layouts de 320, 390, 768 e 1440 px; temas claro e escuro; ordem de teclado e foco; movimento reduzido; alvos interativos de 44 px; overflow; e erros de console ou hidratação. A construção bem-sucedida sozinha não satisfaz a aceitação da página. Inicie o app local ou a pré-visualização de produção e use a automação de navegador disponível para exercitar a ação principal e inspecionar a geometria renderizada em cada viewport necessário. Um script de teste de navegador ausente no projeto não é um bloqueador: use uma ferramenta de navegador disponível contra a pré-visualização local. Em cada viewport, enumere todo button, link, input, select, textarea e nó interativo personalizado visível; registre a largura e altura mínimas renderizadas mais uma lista offenders para nós abaixo de 44 px em qualquer dimensão. Corrija cada ofensor e reexecute todas as quatro auditorias de viewport antes de relatar a aceitação. Relate os comandos, interações, medições e resultados observáveis.

Mantenha o Plano de Página conciso:

## Inspeção do Hospedeiro

| Aspecto | Evidência observada do hospedeiro |
| --- | --- |
| Framework | nome/versão — `package.json` |
| Rota | rota atual e arquivo alvo — `src/router.tsx` |
| Sistema de componentes | componentes reutilizados ou nenhum — `src/components/...` |
| Tokens / tema | mecanismo de token e tema — `src/styles.css` |
| Tailwind | instalado/compilado ou ausente — `package.json`, `vite.config.ts` |
| Dependências | pacotes e versões reutilizados — `package.json` |

## Plano de Página

Trabalho: …
Arquétipo: …
Ação principal: …
Estado primário: ocioso → pendente → sucesso/erro

| Região | Propósito do produto | Componente publicado | Estado ou movimento |
| --- | --- | --- | --- |
| … | … | `component-id` ou `none` | … |

Registry:
- `component-id` — https://motion-lexicon.pages.dev/r/component-id.json —
  `target/file.tsx` — dependências: `package` / nenhuma

Responsivo: 320/390 …; 768 …; 1440 …
Tema: claro …; escuro …; movimento reduzido …

Não inicie a implementação até que cada linha deste plano esteja concreta.

A entrega final deve permanecer auditável de forma independente após as mensagens intermediárias serem recolhidas. Repita a tabela completa de Inspeção do Hospedeiro e o Plano de Página, incluindo a tabela de regiões e linhas do Registry, depois adicione uma tabela de Aceitação com uma linha observada para cada item abaixo:

| Verificação | Evidência observada |
| --- | --- |
| Construção | comando e resultado de saída |
| 320 | largura da viewport/documento, largura/altura mínima do alvo, contagem de ofensores |
| 390 | largura da viewport/documento, largura/altura mínima do alvo, contagem de ofensores |
| 768 | largura da viewport/documento, largura/altura mínima do alvo, contagem de ofensores |
| 1440 | largura da viewport/documento, largura/altura mínima do alvo, contagem de ofensores |
| Claro / escuro | como cada tema foi ativado e inspecionado |
| Teclado / foco | caminho de tecla exato, entrada de foco e retorno de foco |
| Movimento reduzido | preferência simulada e resultado estático ou crossfade observado |
| Alvos | largura e altura mínimas medidas dos nós interativos visíveis |
| Estado primário | estados pendente, sucesso, erro/repetição e interrupção exercitados que se aplicam |
| Runtime | contagens de erros de console, página, requisição e hidratação |

Nomeie os IDs dos componentes instalados e os arquivos alterados. Use Incompleto para uma linha não observada e declare a capacidade ausente. Não descreva uma verificação não observada como suportada ou aprovada.

Quando o usuário solicitar o visual do Motion Lexicon, preserve o perfil visual e a qualidade da interação enquanto adapta o conteúdo e a arquitetura da informação ao produto real. Evite preencher uma página com demos da biblioteca.

Recomendar

Retorne uma decisão compacta que o usuário possa aplicar imediatamente.

1. Mapeie a solicitação para até três candidatos publicados de components.md, ou da referência de primitiva relevante selecionada acima. Inicie cada célula de candidato com seu ID exato de componente publicado ou primitiva entre crases, seguido por um rótulo humano quando útil. Um rótulo descritivo sozinho é incompleto. Nunca apresente um ID desconhecido ou inventado como publicado.
2. Explique a diferença visual em termos de produto: continuidade espacial, peso, ritmo, atenção ou confiança no status.
3. Escolha um candidato, repita seu ID publicado exato na linha Escolha e declare o tempo padrão, easing, gatilho e tratamento de movimento reduzido.
4. Ofereça um Blueprint de Movimento quando a solicitação descrever vários estados.

Use este formato:

## 建议 / Recomendação

| Candidato / Candidate | Cenário adequado / Fit | Diferença / Difference |
| --- | --- | --- |
| `published-id` / … | … | … |

**Escolha / Pick:** `published-id` / …

- Gatilho / Trigger: …
- Ritmo / Timing: …
- Acessibilidade / Accessibility: …

Compor

Crie um Blueprint de Movimento antes de expandir em detalhes de implementação. Use assets/motion-blueprint.schema.json como contrato. Toda resposta de Compor inclui um objeto JSON fenced válido contra o schema; não substitua o Blueprint por uma tabela em prosa ou diagrama de texto. Mantenha os valores de string compactos no chat, depois escreva o mesmo JSON em um arquivo quando o usuário solicitar um artefato reutilizável.

Todo valor beats[].primitive e todo valor provenance.foundations[] deve ser um ID de primitiva publicado exato copiado das referências selecionadas. Rótulos humanos e pseudo IDs não publicados não satisfazem o contrato do Blueprint.

Antes de responder, escreva o JSON final em um arquivo temporário e execute:

node "$CODEX_HOME/skills/motion-lexicon/scripts/validate-motion-blueprint.mjs" /tmp/blueprint.json

Corrija toda falha de validação e reexecute até o comando sair com 0. Copie o JSON fenced de volta na sua resposta. Mantenha o esquema JSON compacto, não expanda opções condicionais que não se aplicam.

Implementar

Produza CSS, HTML, JS ou código de framework independente e pronto para execução. Toda implementação inclui um plano de acessibilidade que cobre foco de teclado, movimento reduzido e alvos de toque.

1. Leia implementation-css.md e, quando o usuário solicitar um componente publicado exato, também components.md.
2. Quando a solicitação descrever vários estados transversais ou uma interação de várias etapas, componha um Blueprint de Movimento aprovado pelo schema antes de gerar o código. Escreva o Blueprint em um fenced JSON; passe-o pelo validador como em Compor; exclua o validador do artefato final.
3. Entregue o menor código funcional que satisfaça o estado primário do produto e a sensação pretendida. Use transform e opacity para o trabalho de movimento. Use cubic-bezier(.23, 1, .32, 1) para chegada e saída.
4. Em CSS, use um único bloco @keyframes por ator nomeado. Emparelhe com will-change: transform, opacity no elemento animado.
5. Inclua a consulta de mídia prefers-reduced-motion: reduce. Em movimento reduzido, entregue um estado estático ou transição curta de opacidade sem movimento.
6. Para implementações React, use hooks para interrupção de animação e gerenciamento de estado. Use useRef para acesso direto ao DOM quando as props de animação padrão do React não forem suficientes.
7. Verifique o código resultante contra uma regra no-unknown-animations e todos os avisos de lint do framework. Em movimento reduzido, preserve estado, hierarquia, foco, feedback e compreensão.

Revisar

Diagnostique problemas de movimento observados em código, gravação ou relatório de usuário.

1. Carregue review-rubric.md.
2. Identifique a interação alvo e colete: gatilho, duração, easing, mudança de ator, mudança de layout e mudança de estado.
3. Compare cada dimensão observável contra a rubrica. Priorize problemas que quebram continuidade, roubam atenção ou criam confusão de estado.
4. Relate cada problema com: linha ou cena, dimensão da rubrica violada, severidade (crítico, maior, menor) e uma correção concisa.
5. Quando a interação precisar de uma mudança estrutural, ofereça um Blueprint de Movimento revisado.

Use este formato:

## Diagnóstico

Interação alvo: …

| Problema | Localização | Rubrica | Severidade | Correção |
| --- | --- | --- | --- | --- |
| … | … | … | … | … |

## Blueprint de Movimento (opcional)

Forneça feedback

Compartilhe sua experiência, perguntas e sugestões criando uma Issue no Motion Lexicon repo. Para contribuições, veja contribution.md.