Aparência

Orbz oferece dois modos de aparência mutuamente exclusivos:

1. selecionar um preset integrado; ou
2. omitir preset e fornecer qualquer um dos cinco atributos color-*.

Não existe atributo ou propriedade palette. O nome público é preset.

Presets integrados

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

Neongate é a aparência padrão mesmo sem preset. Assim, o modo personalizado herda as cores Neongate para valores não fornecidos.

Use nomes e valores exportados ao construir um seletor:

import {
  DEFAULT_ORBZ_PRESET,
  ORBZ_PRESET_NAMES,
  ORBZ_PRESETS,
  type OrbzPresetName,
} from "@neongate-ai/orbz";
 
function getPreview(name: OrbzPresetName) {
  return ORBZ_PRESETS[name];
}
 
const NeongateColors = getPreview(DEFAULT_ORBZ_PRESET);

Nome do preset Neongate

O preset se chama Neongate (neongate), independentemente da conta GitHub. A versão 1.0.1 publicou por engano uma chave de API derivada da conta; a 1.0.2 restaura neongate sem alterar as cores. Esta documentação usa @neongate-ai/orbz@1.0.2.

DEFAULT_ORBZ_PRESET e o getter padrão de preset retornam neongate. Use o nome canônico em novas marcações explícitas:

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

O nome antigo derivado da conta continua aceito em atributos, propriedades, tipos e guards, mas é normalizado para neongate, inclusive na reflexão e no getter. transformOrbzConfiguration() normaliza configurações compactas ou completas antigas sem modificar a entrada.

ORBZ_PRESET_NAMES lista seis nomes canônicos. A chave antiga é um alias imutável e não enumerável de ORBZ_PRESETS.neongate: leituras diretas continuam válidas sem criar uma sétima opção. Para seguir o padrão, prefira DEFAULT_ORBZ_PRESET e ORBZ_PRESETS[DEFAULT_ORBZ_PRESET]. No HTML padrão, omita preset:

<orb-z></orb-z>

Omitir preset também ativa cores personalizadas. Gere opções com ORBZ_PRESET_NAMES do pacote instalado e leia as notas da versão 1.0.2 ao atualizar da 1.0.1.

Paleta personalizada

Remova ou omita preset e defina uma ou mais cores CSS válidas:

<orb-z
  color-primary="#7C3AED"
  color-secondary="#22D3EE"
  color-accent="#F472B6"
  color-highlight="#FDE68A"
  color-background="#09090B"
></orb-z>

As cores podem ser parciais. Valores ausentes herdam o padrão Neongate, então alterar apenas uma cor é válido:

<orb-z color-accent="#FF6B35"></orb-z>

O preset prevalece em conflitos

Não forneça preset e cores personalizadas juntos. Em conflito, Orbz aplica o preset, ignora as cores personalizadas e registra um erro com os atributos conflitantes.

<!-- Invalid: preset wins and color-primary is ignored. -->
<orb-z preset="mocha" color-primary="#7C3AED"></orb-z>

Os atributos personalizados permanecem no host e passam a valer ao remover preset. Por isso, o editor de cores deve alternar modos explicitamente:

const orb = document.querySelector("orb-z");
 
orb?.removeAttribute("preset");
orb?.setAttribute("color-primary", "#7C3AED");

A regra vale em todos os frameworks, que escrevem os mesmos atributos nativos. Remova preset antes de escrever cores personalizadas.

Tamanho e elevação

size controla largura e altura. No HTML, use um comprimento CSS. Na propriedade JavaScript, números positivos são interpretados como pixels.

<orb-z size="18rem" elevated></orb-z>

elevated adiciona uma sombra arredondada e centralizada. É booleano: presença significa verdadeiro, inclusive elevated="false". Para desativar, remova o atributo ou atribua false à propriedade.

O que não é personalizável por decisão de projeto

Variáveis CSS, seletores, camadas e partes internas do Shadow DOM são privados e não formam uma API de temas. Os atributos documentados são o contrato estável, mantendo consistência entre frameworks e liberdade para melhorar a renderização interna.