Integra é um toolkit de design engineering e Agent Skills para orientar agentes de IA na criação, evolução e avaliação de interfaces. Combina contexto de produto, direção visual, conhecimento visual estruturado, workflows de implementação, inspeção local e QA baseado em evidências.
O objetivo não é impor um tema ou gerar interfaces genéricas. É ajudar o agente a compreender o produto, fazer escolhas justificadas, executar o workflow certo e apresentar o que realmente verificou.
Estado da distribuição: o pacote integra-cli ainda não foi publicado no npm. Depois da publicação e confirmação do nome/versionamento, a instalação num projeto será:
npx integra-cli init
npx integra-cli list
npx integra-cli doctorPara testar a distribuição sem escrever no checkout atual, executa a validação do pacote e o smoke test em workspace temporário:
npm run distribution:check
npm run distribution:smokeDepois da publicação, para instalar apenas uma skill especializada noutro projeto:
npx integra-cli add integra-visual-knowledgeA instalação coloca as Agent Skills e o contexto partilhado no workspace. Não instala o runtime TypeScript do Integra nem garante que um host específico carregou ou executou as skills. Consulta o guia do CLI e a matriz de compatibilidade.
O Live Workbench oferece Quick Canvas para pré-visualizações rápidas e Inspector para diagnóstico detalhado. É independente de framework e não acrescenta dependências ao projeto consumidor.
No checkout completo do Integra, regista o plugin no Vite:
import { defineConfig } from 'vite';
import { integraLiveInspectorPlugin } from './src/modules/live-inspector/vite-plugin.js';
export default defineConfig({
plugins: [integraLiveInspectorPlugin()],
});Inicia o servidor normal de desenvolvimento, abre a aplicação local e pressiona Alt + Shift + I. Seleciona um elemento para consultar dimensões, tipografia, classes e contraste estimado. Podes pré-visualizar classes, cor do texto, fundo, padding e border radius; usar Undo/Redo; repor o estado; e exportar um diff textual ou o pacote JSON de revisão.
Pressiona Escape para fechar e restaurar os atributos originais. O atalho pode voltar a abrir o inspector depois de o descartar. O plugin usa apply: 'serve' e não injeta o inspector em builds de produção.
O Live não escreve ficheiros-fonte, não chama providers de IA e não transforma um seletor DOM num caminho de ficheiro. O pacote de revisão marca o mapeamento de source como não verificado; qualquer alteração ao projeto exige inspeção do código e aprovação do diff exato.
Importante: o CLI instala skills e contexto, não este runtime. Para integrar o Live Inspector noutro projeto, mantém o checkout do Integra disponível ou usa uma distribuição runtime futura quando existir.
- Context: normaliza factos, restrições, preferências e informação em falta sem inventar valores.
- Direction: produz um Direction Artifact versionado com decisões nas oito áreas do sistema visual.
- Visual Intelligence: reúne fontes, observações, tokens, padrões, regras e salvaguardas num Bundle offline e determinístico.
- Agent Skills: workflows especialistas para UX, direção, sistema de design, geração, refactor, motion, investigação e QA.
- Live Inspector: inspeção local do DOM e pré-visualizações temporárias/reversíveis.
- Refinement e QA: avaliações com severidade, evidência, confiança e estado de verificação.
- CLI independente: instalação, atualização, diagnóstico e remoção de skills sem executar scripts incluídos no bundle.
| Área | Skill | Responsabilidade |
|---|---|---|
| Orquestração | integra |
Entender o pedido e selecionar o workflow mínimo adequado |
| UX e estrutura | integra-ux-shape |
Jobs, fluxos, navegação, IA e estados |
| Direção visual | integra-design-direction |
Tese visual, composição, identidade e decisões de design |
| Sistema | integra-design-system |
Tokens, componentes, variantes, temas e governação |
| Cor | integra-colorize |
Cor semântica, hierarquia, temas e contraste |
| Motion | integra-animate |
Transições, micro-interações, timing, reduced motion e performance |
| Implementação | integra-ui-generator |
Novos ecrãs, componentes e interações |
| Manutenção | integra-refactor-agent |
Refactor com preservação do comportamento |
| Revisão | integra-design-qa |
UX, qualidade visual, estados e responsividade |
| Acessibilidade | integra-accessibility-audit |
Auditoria WCAG com evidência por critério |
| Performance | integra-performance-audit |
Medição e diagnóstico de gargalos |
| Investigação | integra-investigation |
Pesquisa técnica e de produto baseada em fontes |
| Referências | integra-reference-investigator |
Observação e adaptação original de referências |
| Inteligência visual | integra-visual-knowledge |
Curadoria e retrieval de fontes, tokens, padrões, regras e exemplos |
| Inspeção | integra-live-inspector |
Preview de DOM local e handoff para source |
integra-direction é mantida como alias legado de integra-design-direction para compatibilidade. Os nomes canónicos seguem o padrão integra-<capacidade>; não renomeamos skills já distribuídas sem uma estratégia de migração.
O catálogo commands/manifest.json descreve comandos, modificadores, gatilhos, skills, inputs, outputs e política de alteração de source. O routing determinístico está disponível no módulo src/modules/commands; inclui o workflow /integra:visual-intelligence.
O manifesto é agnóstico ao host. A sua presença não significa que Codex, Gemini CLI, Cursor, Claude Code ou Copilot tenham registado comandos nativos automaticamente. A descoberta e invocação dependem do suporte e configuração de cada host.
npm run direction:generate -- --stdoutO comando usa o fixture DL-001 por omissão e escreve o Direction Artifact validado no stdout. Para o guardar numa execução local:
npm run direction:generateO destino predefinido é .integra/runs/direction/DL-001.json.
npm run visual-intelligence:generate -- \
--artifact .integra/runs/direction/DL-001.json \
--task "Explain the product value and invite visitors to try a demo" \
--mode persuade \
--niche-id saas-developer-aiO comando produz um Visual Intelligence Bundle 1.1.0 em .integra/runs/visual-intelligence/bundle.json. A tarefa é obrigatória; modo e nicho são fornecidos pelo chamador e não são inferidos automaticamente. Usa --stdout para receber JSON no stdout, ou --query, --tag, --asset-type e --limit para orientar o retrieval. Para validar um Bundle já recebido ou guardado, executa npm run visual-intelligence:validate -- --input .integra/runs/visual-intelligence/bundle.json.
O Bundle separa decisões do Direction Artifact de candidatos de conhecimento. Fontes catalog-only, observações partial, observações verificadas, receitas de tokens e padrões não são equivalentes nem se transformam automaticamente em decisões aprovadas.
npm run pilot:prepareO comando prepara um pacote manual em .integra/runs/pilots/DL-001/ com brief, prompt comum, Direction Artifact, Bundle, instruções para a condição guiada, critérios de aceitação e hashes. Executa o mesmo agente em duas cópias limpas: baseline (brief + prompt) e Integra-guided (os mesmos materiais + artefactos). O comando não invoca o agente nem cria a interface. Segue o protocolo do primeiro piloto.
Depois da execução guiada, valida a cobertura do relatório do agente:
npm run direction:consumption:validate -- --artifact .integra/runs/pilots/DL-001/direction.json --report ./consumption-report.jsonEste validator confirma schema, ligação ao artefacto e cobertura de todos os IDs de decisão/recomendação. O relatório continua a ser autorrelato e não prova qualidade da implementação.
O agente externo recebe o Bundle e implementa no projeto de destino segundo o seu próprio contrato de execução. O Live Inspector pode depois recolher previews e exportar um pacote de revisão. O source mapping é resolvido separadamente; o Bundle e o pacote Live não são prova de implementação nem um QA pass.
Quando disponíveis, PRODUCT.md e DESIGN.md ajudam a preservar a verdade do produto e o sistema visual aprovado. O contrato e os modelos opcionais estão em docs/product-context-contract.md e templates/. Para produtos existentes, refinamento preserva a identidade por defeito; uma mudança de mundo visual requer pedido ou aprovação explícita.
- Produto antes da decoração: começa pelo trabalho do utilizador, conteúdo e contexto.
- Direção original: referências informam princípios; não são copiadas como páginas, assets ou identidade.
- Menor workflow útil: não chamar todas as skills quando uma especialista basta.
- Decisões rastreáveis: separar factos, restrições, preferências, pressupostos e desconhecidos.
- Acessibilidade desde o início: semântica, teclado, foco, contraste, estados e reduced motion.
- Motion com propósito: cada animação comunica estado, continuidade, feedback ou intenção visual clara.
- Evidência antes de claims:
not_run,inconclusivee heurísticas nunca são convertidos empassed. - Alterações seguras: preservar trabalho existente e exigir aprovação do diff exato antes de editar source.
O core determinístico é provider-agnostic. Os módulos de contexto, direção, knowledge, investigação, refinamento, QA e Live Inspector comunicam através de contratos explícitos. As Agent Skills são a camada de instruções para os agentes; o CLI empacota as skills canónicas e recursos de contexto partilhados.
Consulte:
- Arquitetura
- Visual knowledge routing
- Design Intelligence Library
- Compatibilidade e instalação por host
- Contrato de contexto de IA
- Contrato de integração dos agentes
- Contrato de contexto e identidade
- Protocolo do primeiro piloto DL-001
- Especificação do Live Inspector
- Avisos e licenças de terceiros
A biblioteca separa fontes visuais, providers de assets, mapeamentos para os 61 nichos existentes, observações por página, receitas semânticas de tokens, padrões de layout, regras, anti-patterns e exemplos. O resolver é offline-first e devolve candidatos explicáveis, sem navegar em sites, aplicar tokens ou declarar defeitos automaticamente. Novas fontes permanecem catalog-only até inspeção específica.
As observações de referência são page-scoped. Uma observação documental não verifica todo o produto ou fonte; os seus limites e estado são preservados no Bundle.
Requisitos do checkout completo:
- Node.js 24 (intervalo suportado:
>=24 <27). - npm 10 ou superior.
Executa:
npm ci
npm run check
npm run distribution:smokeValidações focadas:
npm run pilot:prepare
npm run design:qa -- ./src --json
npm run design:qa -- ./src --json
npm run pilot:prepare
npm run validate:visual-library
npm run validate:skills
npm run validate:agent-assets
npm run validate:commands
npm run distribution:checkO validador de skills verifica frontmatter, nomes, limites do formato e links locais. O bundler verifica recursos e integridade antes de criar o bundle do CLI. Estes checks não provam que um host específico carregou ou executou uma skill.
- O CLI não executa scripts do bundle e não instala o runtime TypeScript do repositório.
- Instalar uma skill não garante que um host a tenha descoberto, ativado ou seguido.
- O routing prepara um plano; não é um executor universal de agentes.
- O Live Inspector é apenas para desenvolvimento local; não edita source nem deve ser usado em produção.
- O Design QA estático lê JSX/TSX e CSS e produz sinais heuristic com localização e evidência de source. Não é uma auditoria runtime: teclado, screen readers, layout renderizado, contraste compositado, estados e performance continuam a exigir teste independente.
- Uma auditoria parcial não prova conformidade WCAG global.
- Uma recomendação de performance sem medições não é um ganho comprovado.
O Integra é distribuído sob MIT. A skill integra-animate e a adaptação existente de integra-colorize incorporam orientação adaptada do Impeccable, licenciado sob Apache-2.0. O bundle inclui o texto integral dessa licença e os avisos necessários em docs/third-party-notices.md e licenses/.
O Integra não incorpora o CLI, binários, extensão de browser, scripts ou dependências runtime do Impeccable.