Design system

Todo o visual do IDPlugger UI vem de CSS custom properties publicadas em @handsondigital/idplugger-ui/tokens.css. Elas ficam em quatro camadas: cada uma aponta para a anterior, e os componentes só leem as duas últimas. Por isso uma marca nova troca a identidade sem tocar em nenhum componente.

As camadas

Camada	Prefixo	Papel	Exemplo
1. Primitivo	`--color-<escala>-<passo>`, `--size-*`	Valores brutos do Figma, sem intenção de uso	`--color-gray-500`, `--size-4`
2. Marca	`--color-brand-`, `--font-brand-`, `--radius-brand`	Contrato que cada marca sobrescreve	`--color-brand-primary`
3. Semântico	`--color-surface`, `--color-foreground`, `--color-border`, `--color-focus-`, `--color-action-<tom>`, `--color-feedback-<status>*`	Intenção de uso; deriva da marca e muda com o modo de cor	`--color-action-primary`
4. Componente	`--<componente>-`: `--button-`, `--input-`, `--card-`, `--tabs-`, `--alert-`, `--upload-*`…	O que cada componente lê; aponta para semânticos	`--button-primary-bg`

O tokens.css traz ainda a densidade (data-density, que ajusta espaçamentos do botão) e o bloco @theme do Tailwind 4, que expõe estes tokens como utilitários. Não são camadas novas: leem as camadas acima.

O fluxo, de baixo para cima:

primitivo        marca                   semântico                    componente
--size-4   ──▶   --color-brand-primary ──▶ --color-action-primary ──▶ --button-primary-bg ──▶ .app-button

O que cada camada permite

Trocar a marca: sobrescreva a camada de marca (ver Marcas e presets). Hover, pressionado, foco e desabilitado derivam dessas cores.
Ajustar um componente sem mudar a marca: sobrescreva o token dele, por exemplo --button-shadow.
Estilizar o CSS do seu hotsite: use tokens semânticos (--color-surface, --color-foreground) em vez de hex ou das escalas. Eles acompanham a marca e o modo.

Escopo: marca e modo valem para a subárvore

Semânticos e tokens de componente são redeclarados em todo elemento com data-brand ou data-theme. Assim uma seção da página pode ter outra marca ou outro modo; veja Marcas e presets e Modo escuro.

Tokens de modo de cor seguem o padrão color-mix(in srgb, <escuro> var(--theme-dark), <claro>): com --theme-dark: 0% o resultado é exatamente o valor claro.

Tokens para designers e ferramentas

Para ferramentas de design e agentes de IA, o pacote publica os mesmos tokens em JSON no formato DTCG: @handsondigital/idplugger-ui/tokens.dtcg.json. Serve para importar no Tokens Studio ou nas variáveis do Figma. O arquivo traz:

primitive: as escalas primitivas;
brand.<marca>: o contrato completo de cada marca;
semantic.<marca>.light e semantic.<marca>.dark: os tokens semânticos já resolvidos para cor concreta em cada marca e modo. O nome da variável CSS correspondente está em $extensions (cssVar).

Onde ver cada camada

Cores da marca, semânticas e escalas: Cores.
Escala --size-* e raio: Espaçamento e raio.
Densidade (tokens --button-gap e --button-icon-size, entre outros): Densidade.