For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /pt/docs/web/theming.md (or send Accept: text/markdown).

Temas de produto

Personaliza o chrome de produto do kit para o teu SaaS — sem modificar o tema de marca do marketing.

Perguntar sobre este guia

Instalação e configuração

Antes de qualquer etapa, leia Antes de começar e Noções básicas sobre terminal. Estas instruções presumem que você abriu o monorepo supastack completo no VS Code; sua raiz package.json marca a raiz do repositório. Nos comandos pnpm, um pacote de espaço de trabalho é um aplicativo ou uma pasta de código compartilhado; no produto, um espaço de trabalho é o contêiner de dados e o limite de segurança de uma equipe. corepack pnpm --filter ... seleciona um pacote do monorepo enquanto os comandos são executados a partir de sua raiz. Se você abriu apenas uma pasta móvel ou desktop sincronizada, ela não contém o back-end da Web, a configuração do Docker ou os scripts raiz: execute o back-end deste monorepo ou de um servidor hospedado acessível e use os próprios scripts da pasta da plataforma. Uma variável de ambiente é uma configuração nomeada armazenada em um arquivo .env local ou no painel de hospedagem; reinicie o aplicativo relevante após alterá-lo e mantenha os segredos do servidor fora dos valores NEXT_PUBLIC_ e EXPO_PUBLIC_.

1. No VS Code, abra apps/web/app/app-theme.css para telas de produtos conectados e apps/web/src/theme/catalog.ts para adicionar um pacote de cores. Não edite apps/web/app/theme.css para cores do produto; ele controla a marca de marketing.

2. Na raiz do repositório, execute corepack pnpm --filter @supastack/web dev e visite http://localhost:3000/settings/appearance.

3. Altere um token em sua filial local e atualize a visualização. Esperado: os controles do painel são atualizados enquanto a página inicial mantém o tema de marketing selecionado.

A marca de marketing e o tema de produto são ficheiros separados. Edita apps/web/app/app-theme.css para o chrome de dashboard, auth, settings, billing, chat e org. Adiciona pacotes de cores em apps/web/src/theme/catalog.ts. Estende os eixos densidade, raio, fonte e layout em apps/web/src/theme/presets.ts mais as regras html[data-*] correspondentes em app-theme.css. Escolhe a identidade de marketing em apps/web/src/theme/marketing-theme.ts (MARKETING_THEME_MODE: locked | inherit | um id de pack) em vez de editar apps/web/app/theme.css — o seu bloqueio via .marketing-theme:not(.app-theme):not([data-theme]):not([data-marketing-theme="inherit"]) mantém a marca Obsidian da página inicial do supastack por defeito.

Em tempo de execução, Configurações → Aparência → ThemePicker armazena cor, densidade, raio, fonte e layout em cookie do navegador + localStorage para que theme-boot.ts restaure todos os eixos antes da primeira pintura, e sincroniza o pacote completo de aparência do usuário conectado entre navegadores por meio de user_appearance (GET/PUT /api/account/appearance). A mesma página monta a galeria de UI do kit para que pacotes e predefinições atualizem ao vivo botões, campos, cartões, selos e diálogos. Detalhes de design e exemplos prontos para copiar estão em docs/design/kit-product-theme.md e docs/design/kit-ui-gallery.md.

/* Edit product chrome here — not theme.css */
.app-theme {
  --radius-card: 14px;
  background: var(--page);
  color: var(--text);
}
.app-theme .button-primary {
  background: var(--accent);
  color: var(--accent-ink);
}

/* catalog.ts — append a ThemeDefinition with every THEME_TOKEN_NAMES entry */
{
  id: "coral",
  name: "Coral",
  colorScheme: "light",
  tokens: { "--page": "#fff7f4", "--accent": "#e06b4f" /* …full token set… */ }
}

Comandos para copiar

Siga os comentários para ver em qual pasta um comando é executado. Se dois terminais estiverem rotulados, abra duas janelas de terminal e mantenha o primeiro comando em execução enquanto usa o segundo.

corepack pnpm --filter @supastack/web dev

# In a second terminal, after changing a theme token:
corepack pnpm test -- apps/web/src/theme/contrast.test.ts

Fluxo de implementação

Ao adicionar um pack, mantém contrast.test.ts verde. Ao adicionar um id de preset, atualiza presets.ts e os remaps html[data-density|data-radius|data-font|data-layout] em app-theme.css para que ThemePicker e o boot anti-FOUC fiquem alinhados.

Preserva a geometria de marca de quatro mosaicos partilhada em marketing/brand-geometry.ts para superfícies de marketing. As marcas de cabeçalho ficam transparentes; os assets de favicon e ícone de app mantêm o fundo negro arredondado. Páginas puramente de marketing ficam Obsidian enquanto MARKETING_THEME_MODE for "locked" (o defeito do kit); os produtos podem fixar outro pack ou herdar a escolha do visitante.

Verificação e resolução de problemas

Se uma mudança de cor afetar a página inicial de marketing, verifique se você editou app-theme.css e revise apps/web/src/theme/marketing-theme.ts.. Se o texto ficar difícil de ler, restaure o valor anterior e execute corepack pnpm test -- apps/web/src/theme/contrast.test.ts a partir da raiz antes de tentar novamente.

Depois de modificar tokens ou packs de tema do kit, verifica que ThemePicker em /settings/appearance atualiza a galeria de UI do kit mais /dashboard, /auth, /billing, /chat e os shells de org. Confirma que / permanece no bloqueio Obsidian de marketing (a menos que MARKETING_THEME_MODE diga outra coisa). Corre os contratos unitários de tema (catalog, presets, contrast, theme-ownership, kit-ui-gallery) e o Playwright application-theme quando disponível. Verifica foco de teclado, contraste, 320 px e movimento reduzido.