Solução de problemas

A tag aparece, mas o orb não

O navegador provavelmente não registrou o elemento personalizado. Importe a entrada do navegador no cliente:


import "@neongate-ai/orbz/browser";

Depois, inspecione o registro:


console.log(customElements.get("orb-z"));

Em React ou Next.js, importe @neongate-ai/orbz/browser no cliente e renderize <orb-z> diretamente. Não importe arquivos-fonte do pacote.

O servidor informa que `HTMLElement` ou `customElements` não está definido

Use uma entrada documentada do pacote, em vez de executar código exclusivo do navegador no servidor. As entradas raiz e browser protegem o registro, mas seu código não deve acessar globais do DOM durante SSR.

Mova consultas DOM para a inicialização cliente, um efeito ou hook de montagem. Veja SSR e hidratação.

TypeScript não reconhece `<orb-z>` no React

Adicione a tag a React.JSX.IntrinsicElements conforme o guia React e Next.js. Não crie um wrapper para resolver: o elemento em execução continua sendo <orb-z>.

Conflito entre preset e cores personalizadas

Escolha um modo: use preset ou remova-o e defina color-*. Com ambos presentes, o preset prevalece e Orbz registra os atributos conflitantes.

`palette` não tem efeito

palette não é um atributo ou propriedade pública. Use preset:


<orb-z preset="magenta"></orb-z>

Os presets são Neongate (padrão), periwinkle, magenta, peach, mocha e ivory. Leia as chaves em ORBZ_PRESET_NAMES; veja nomes dos presets.

Uma cor personalizada não aparece

Remova preset antes de entrar no modo personalizado:


orb.removeAttribute("preset");
orb.setAttribute("color-primary", "#7C3AED");

Verifique também se a cor CSS é válida e o atributo é um dos cinco suportados: color-primary, color-secondary, color-accent, color-highlight ou color-background.

`paused="false"` ou `elevated="false"` continua ativado

São atributos booleanos HTML: presença significa verdadeiro, qualquer que seja a string. Remova o atributo:


orb.removeAttribute("paused");
orb.removeAttribute("elevated");

Ou use as propriedades correspondentes:


orb.paused = false;
orb.elevated = false;

Em frameworks com templates, vincule null ou undefined quando o atributo não deve existir.

A animação não está rodando

Verifique os controles nesta ordem:

Remova paused ou defina a propriedade como false.
Confira reduced-motion: always usa um perfil estático.
Com system, confira a preferência do sistema operacional.
Confirme que speed é positivo.
Confirme que o elemento está conectado e registrado.

restart() reconstrói a animação atual, mas não ignora pausa nem a política de movimento reduzido.

Estado, velocidade ou preset incorreto

Valores não suportados são normalizados para padrões seguros:

Controle	Padrão
`state`	`idle`
`speed`	`1`
`preset`	`DEFAULT_ORBZ_PRESET` (Neongate)
`reduced-motion`	`system`
`size`	`16rem` para valor vazio ou propriedade numérica inválida

Use os tipos TypeScript e constantes exportados para detectar valores inválidos antes da execução.

Vue avisa que não consegue resolver `orb-z`

Configure o compilador de templates do Vue para tratar a tag como elemento personalizado:


vue({
  template: {
    compilerOptions: {
      isCustomElement: (tag) => tag === "orb-z",
    },
  },
})

Importe também @neongate-ai/orbz/browser na entrada cliente do Vue.

Angular informa que `orb-z` é um elemento desconhecido

Adicione CUSTOM_ELEMENTS_SCHEMA ao componente independente ou NgModule responsável pelo template:


schemas: [CUSTOM_ELEMENTS_SCHEMA]

Depois importe a entrada do navegador antes de inicializar a aplicação.

Dois microfrontends carregam versões diferentes

O registro Custom Elements aceita uma definição por tag. Orbz protege contra duplicação: a primeira implementação registrada prevalece. Coordene uma versão exata entre remotes ou deixe o shell registrar. Veja Orbz em microfrontends.

Não consigo inspecionar ou estilizar o Shadow DOM

A raiz shadow é fechada por projeto. Variáveis CSS públicas, partes, classes e camadas internas não são suportadas. Use os atributos documentados. Se eles não cobrem um caso de uso compartilhado válido, abra uma proposta focada no GitHub Issues .

Ainda com dificuldades?

Ao abrir uma issue, inclua:

versão do Orbz e ponto de entrada
framework e versão
navegador e sistema operacional
menor HTML <orb-z> que reproduz o problema
saída relevante do build ou console

Abrir uma issue do Orbz · Ver o pacote npm