Por que times perdem meses em temas

Seis dores recorrentes de quem precisa entregar multi-tema, whitelabel ou dark mode — e que o Aplica DS resolve com uma única config.

Valores hardcoded

#2563EB repetido em 50+ arquivos. Trocar a cor da marca vira busca-e-substituição manual em todo o código.

Dark mode = refazer tudo

Cada cor nova exige uma variante escura manual. Tokens dobram, bugs também.

Plataformas divergem

CSS, React Native e Figma vivem em mundos separados. A divergência é questão de tempo.

Sem contrato semântico

blue-500 é cor, não papel. Sem camada de decisão, engenheiros adivinham — e erram.

Nova marca = fork do sistema

Whitelabel sem arquitetura vira fork. Cada marca nova multiplica o custo de manutenção.

Preso a uma component library

Trocar de Radix para Base UI, ou usar um DS proprietário, significa refazer tokens do zero. O Aplica DS é agnóstico: a camada semântica conecta a qualquer library via Skills de integração.

POR QUE APLICA DS

Não é só mais um gerador de tokens

Style Dictionary resolve saída multi-plataforma. CSS variables resolvem personalização local. O que falta em ambos é a camada semântica que dá intenção aos tokens.

	CSS vars manual	Style Dictionary	Aplica DS
Estrutura semântica de 5 camadas	—	—	✓
Dark mode por construção (OKLCh)	—	—	✓
Multi-marca a partir de uma config	—	—	✓
Output multi-plataforma (CSS, JSON, TS…)	—	✓	✓
Pipeline determinístico (mesma config → mesmo output)	—	parcial	✓
Acessibilidade algorítmica embutida	—	—	✓

Estrutura semântica de 5 camadas

CSS vars — Style Dictionary — Aplica DS ✓

Dark mode por construção (OKLCh)

CSS vars — Style Dictionary — Aplica DS ✓

Multi-marca a partir de uma config

CSS vars — Style Dictionary — Aplica DS ✓

Output multi-plataforma (CSS, JSON, TS…)

CSS vars — Style Dictionary ✓ Aplica DS ✓

Pipeline determinístico (mesma config → mesmo output)

CSS vars — Style Dict. parcial Aplica DS ✓

Acessibilidade algorítmica embutida

CSS vars — Style Dictionary — Aplica DS ✓

SEMÂNTICA + IA

Tokens que comunicam intenção — não apenas valores

Um token semântico não guarda uma cor. Guarda um significado. Isso muda o que ferramentas, engenheiros e agentes de IA conseguem fazer com ele.

Contexto comprimido para IA

Um agente que lê action.bg.danger.default entende o propósito sem precisar de prompt adicional. Semântica é documentação legível por máquina, nativa no token.

Marcas ilimitadas, zero reescrita

O contrato semântico é fixo. Os valores mudam por marca, modo ou superfície. Adicionar uma nova marca é configurar — não refatorar. O sistema cresce sem dívida técnica.

Um contrato para humanos, engenheiros e agentes

Designer, dev e LLM leem o mesmo token e chegam à mesma conclusão. Semântica elimina a tradução entre disciplinas — e entre ciclos de produto.

NOVO · v3.5

AI Skills — Cursor, Claude Code e Copilot

aplica-theme-engine ai:init injeta skills de integração no workspace. Agentes entendem camadas, estados, txtOn, txt e archetypes de componente — sem hardcode, sem adivinhação de nomes de variável.

NOVO · v3.6

Contrato de cor expandido — token `txt`

O contrato de cor passou de 3 para 4 partes: background / txtOn / border / txt. O token txt é a cor legível de texto sobre canvas — diferente de txtOn, que é texto sobre o próprio background colorido. Aliases planos em foundation.txt.*.

NOVO · v3.7

Output tipado — `jsonTyped`

Novo formato de output com metadata estruturada por token: type, value, description e path — campos com nomes configuráveis. Ideal para tooling, code generators e agentes de IA que precisam de contexto além do valor bruto.

Veja na prática — o mesmo token resolvendo de forma diferente em cada marca:

Playground de Temas

Mude marca, modo e superfície. Os tokens Foundation resolvem em tempo real pela camada Semantic.

Marca

Modo

Superfície

Tema Ativo:Joy·light·positive

Tipografia

DISPLAY — fontFamilies-display

Display titles

TITLE — heading-title_2

Heading Title — fontFamilies-main

BODY — content-body

Body text with the theme's main font.

LABEL — content-label

Interface label / caption

CODE — fontFamilies-code (IBM Plex Mono)

--foundation-bg-brand-default

Foundation Colors

txt-title

bg-primary

txt-body

bg-secondary

txt-on-brand-default

bg-brand-default

txt-on-feedback-info

feedback-info

txt-on-feedback-success

feedback-success

txt-on-feedback-warning

feedback-warning

txt-on-feedback-danger

feedback-danger

Componentes

Card de Exemplo

Componente com tokens Semantic para fundo, texto e borda.

Cadeia de resolução

Foundation

→ semantic.color...

foundation.bg.brand.default

Alias curto para times de produto

Semantic

→ surface.color...

semantic.color.brand.branding
  .first.default.background

Token com propósito — não cor, mas papel

Surface

→ mode.interface...

surface.color.brand.branding
  .first.default.background

Contexto de superfície: positive / negative

Mode

→ theme.color.light.brand.branding.first.lowest.background

mode.interface.positive.branding
  .first.default.background

Contexto de luminosidade: light / dark

Brand

#e7398a

theme.color.light.brand.branding.first.lowest.background

Valor primitivo da marca Joy

Valor resolvido

Resolvendo...

Valor final:

var(--resolving)

COMO FUNCIONA

Do config ao token em 6 passos

Um arquivo de configuração. Um pipeline determinístico. Tokens consistentes, acessíveis e prontos para qualquer plataforma.

[01]

Verificação de estrutura

Garante que pastas e arquivos de dados existem. Falha rápido se algo estiver faltando.

[02]

Escala dimensional

Gera a escala de espaçamento em 3 variantes: minor (8px), normal (16px), major (24px). Progressão geométrica, 10 passos cada.

[03]

Pipeline OKLCh

Decompõe cada cor da marca em 19 níveis de luminosidade no espaço perceptual OKLCh. Dark mode derivado matematicamente: dark[N] = light[20−N].

[04]

Sincronização de camadas

Mapeia paleta → Mode → Surface → Semantic. Produz 4 variantes de tema: light-positive, light-negative, dark-positive, dark-negative.

[05]

Foundation aliases

Gera aliases curtos para times de produto: foundation.bg.primary, foundation.txt.title, foundation.spacing.medium — todos apontando para a camada Semantic.

[06]

Build multi-plataforma

Style Dictionary compila os tokens gerados em CSS Custom Properties, JSON, ESM, CJS e TypeScript declarations — prontos para web, mobile e Figma.

O resultado em código

01 · Config

Configure o engine em aplica-theme-engine.config.mjs.

import { defineThemeEngineConfig }
  from '@aplica/aplica-theme-engine/config';

export default defineThemeEngineConfig({
  paths: {
    configDir: './theme-engine/config',
    dataDir:   './data',
    distDir:   './dist'
  }
});

02 · Build

Um comando executa o pipeline completo.

# CLI direto
npx theme-engine build

# ou via package.json
npm run tokens:build

03 · Uso

Foundation tokens prontos para qualquer plataforma.

@import './dist/css/foundation/engine/
         foundation.css';

.btn {
  background: var(--foundation-bg-brand-default);
  color:      var(--foundation-txt-title);
  padding:    var(--foundation-spacing-medium);
}

PARA QUEM

Três perfis, um engine

Cada trilha tem 6 tutoriais progressivos. Do designer que usa o Figma até o engenheiro que integra tokens em Radix, Base UI ou qualquer DS proprietário.

TRILHA N1

Product Designer

Usa o sistema no Figma. Aprende vocabulário de tokens, acessibilidade embutida e dark mode automático via Tokens Studio.

6 tutoriais · ~3h Começar N1 →

TRILHA N2

System Designer

Configura e governa o Theme Engine. Cria temas, gerencia cores de produto e define sobreposições responsáveis. Compreende a arquitetura semântica para entregar whitelabel.

6 tutoriais · ~4h · Pré-req: N1 Começar N2 →

TRILHA N3

Design Engineer

Implementa componentes conformantes. Integra tokens em React, Vue, React Native, Flutter ou qualquer component library (Radix, Base UI, próprio). Adiciona marcas ao engine via um único arquivo de config.

6 tutoriais · ~5h · Pré-req: N2 Começar N3 →

Temas semânticos para qualquer UI library.

Por que times perdem meses em temas

Valores hardcoded

Dark mode = refazer tudo

Plataformas divergem

Sem contrato semântico

Nova marca = fork do sistema

Preso a uma component library

Não é só mais um gerador de tokens

Arquitetura de 5 Camadas

Tokens que comunicam intenção — não apenas valores

Contexto comprimido para IA

Marcas ilimitadas, zero reescrita

Um contrato para humanos, engenheiros e agentes

AI Skills — Cursor, Claude Code e Copilot

Contrato de cor expandido — token `txt`

Output tipado — `jsonTyped`

Playground de Temas

Cadeia de resolução

Valor resolvido

Do config ao token em 6 passos

Verificação de estrutura

Escala dimensional

Pipeline OKLCh

Sincronização de camadas

Foundation aliases

Build multi-plataforma

Três perfis, um engine

Product Designer

System Designer

Design Engineer

100% open source

Por onde começar?

Product Designer

System Designer

Design Engineer

Temas semânticos para qualquer UI library.

Por que times perdem meses em temas

Valores hardcoded

Dark mode = refazer tudo

Plataformas divergem

Sem contrato semântico

Nova marca = fork do sistema

Preso a uma component library

Não é só mais um gerador de tokens

Arquitetura de 5 Camadas

Tokens que comunicam intenção — não apenas valores

Contexto comprimido para IA

Marcas ilimitadas, zero reescrita

Um contrato para humanos, engenheiros e agentes

AI Skills — Cursor, Claude Code e Copilot

Contrato de cor expandido — token txt

Output tipado — jsonTyped

Playground de Temas

Cadeia de resolução

Valor resolvido

Do config ao token em 6 passos

Verificação de estrutura

Escala dimensional

Pipeline OKLCh

Sincronização de camadas

Foundation aliases

Build multi-plataforma

Três perfis, um engine

Product Designer

System Designer

Design Engineer

100% open source

Por onde começar?

Product Designer

System Designer

Design Engineer

Contrato de cor expandido — token `txt`

Output tipado — `jsonTyped`