shaharsha/claude-skill-brand-system

Sistema de Marca

Cria um livro de marca + sistema de design que reside na raiz do repositório de um produto web — BRAND.md longo (a referência de trabalho, 20 seções) emparelhado com BRAND.html (a destilação para stakeholders, imprimível, ~7 páginas A4, renderizado para BRAND.pdf via Chrome headless) e um tokens.css correspondente para o @theme do Tailwind v4.

Esta habilidade cria o documento. Sua irmã brand-assets produz os pixels (favicons SVG, pacote PWA, apple-touch-icon). Chame ambas em sequência para um lançamento de marca completo.

Os cinco artefatos

Artefato	O quê	Como
BRAND.md	Referência de trabalho longa com 20 seções	templates/BRAND.md.tmpl via scripts/new-brand-book.sh
BRAND.html	Destilação imprimível de 7 páginas A4	templates/BRAND.html.tmpl via mesmo script
BRAND.pdf	Renderizado via Chrome headless	scripts/render-pdf.sh
tokens.css	@theme do Tailwind v4 + :root + [data-theme="dark"]	templates/tokens.css.tmpl + scripts/extract-tokens.py
tokens.json	Formato W3C DTCG para Style Dictionary / Tokens Studio	scripts/extract-tokens.py --format dtcg

Fluxo de trabalho (árvore de decisão)

1. Começando do zero? — execute a entrevista de movimentos de assinatura primeiro: copie templates/signature-interview.md.tmpl para o repositório e responda cada pergunta antes de criar a estrutura. Veja reference/signature-moves.md para saber por que cada pergunta é importante. Sem isso, a saída é um modelo; com isso, é uma marca.

2. Criando um novo livro? — execute scripts/new-brand-book.sh com as respostas da entrevista como sinalizadores. Emite BRAND.md, BRAND.html, tokens.css, signature-interview.md no diretório de saída.

3. Esboçando um capítulo específico? — carregue a referência correspondente:

   • §0 a ideia / §2 primitiva / §3 movimentos de assinatura → reference/signature-moves.md
   • §5 logotipo + pacote de favicon → reference/favicon-pack.md
   • §6 cor → reference/color.md + reference/tokens.md
   • §7 tipografia → reference/typography.md
   • §10 superfícies e materiais → reference/surfaces.md
   • §11 movimento → reference/motion.md
   • §13 voz e tom → reference/voice-and-tone.md
   • §14 acessibilidade → reference/accessibility.md
   • §17 @theme do Tailwind v4 → reference/tailwind-v4.md
   • Hebraico / Árabe / RTL → reference/rtl.md

4. Pacote de favicon + PWA? — não gere recursos nesta habilidade. reference/favicon-pack.md especifica os requisitos (favicon SVG consciente do sistema, apple-touch-icon opaco, PWA mascarável, par OG claro+escuro). Passe a especificação + um SVG fonte para o script icon-pack.sh da habilidade brand-assets.

5. Auditoria de contraste antes do lançamento → scripts/audit-contrast.py. WCAG 2.2 AA no corpo (4.5:1), 3:1 em grande / UI / anéis de foco. Executa por tema (claro + escuro). Cole a matriz na §14.

6. Renderizando o PDF → scripts/render-pdf.sh. Chrome headless. Produz BRAND.pdf a partir de BRAND.html.

7. Auditando um livro existente → scripts/audit-outline.py. Valida o sumário de 20 seções, sinaliza entradas de registro de decisão ausentes, alerta se a §2 primitiva de assinatura tiver menos de 8 locais de uso documentados.

8. Detectando desvio entre BRAND.md e CSS de produção → scripts/check-consistency.py. Os livros de marca falham quando o código diverge silenciosamente deles. Compara tokens de cor em BRAND.md com um ou mais arquivos CSS de destino e sai com código diferente de zero em caso de desvio hexadecimal. Integre no CI.

9. Impondo a entrevista antes da criação → passe --require-interview caminho/para/signature-interview.md para scripts/new-brand-book.sh. Recusa-se a criar se a entrevista ainda tiver {{PLACEHOLDER}}, {{TODO}} ou linhas de resposta > … não preenchidas. Altamente recomendado.

Regras da casa

1. Exija os movimentos anti-modelo antes de criar. A entrevista não é opcional. Um substantivo próprio inventado, três princípios falseáveis, três 'não faça' reais de erros passados, uma amostra de voz de 150 palavras na voz da marca e um movimento de assinatura que deliberadamente quebra uma prática recomendada. Sem isso, o livro é um modelo. Veja reference/signature-moves.md.

2. Acento constante entre claro/escuro. Apenas os tokens semânticos de superfície e texto trocam entre os temas. A única cor de marca saturada é idêntica em ambos os modos — é isso que permite que uma primitiva de assinatura signifique a mesma coisa independentemente da preferência do sistema. Codificado em templates/tokens.css.tmpl.

3. Tokens de três níveis conforme taxonomia de Nathan Curtis. Primitivo (--color-cream: #F3EAD3) → semântico (--bg: var(--color-cream)) → componente (--btn-bg: var(--bg-elevated)). Primitivos vão em @theme, semânticos em :root, substituições do modo escuro em [data-theme="dark"]. Veja reference/tokens.md.

4. WCAG 2.2 AA é o piso legal em 2026. Não APCA — APCA foi removido do WCAG 3 em julho de 2023 e não retornou. AA significa corpo 4.5:1, grande/UI/foco 3:1, tamanho mínimo de alvo 24×24. Auditado com scripts/audit-contrast.py; veja reference/accessibility.md.

5. RTL é um fundamento, não um apêndice. Se o produto for lançado em hebraico ou árabe, use propriedades lógicas de CSS (margin-inline-start, não margin-left) desde o primeiro dia; o custo de retrofit é 10–50 vezes o de projetar para isso antecipadamente. Veja reference/rtl.md.

6. O livro de marca é ele próprio uma instância da marca. O modelo BRAND.html usa a própria paleta + tipo do produto — para que o documento pareça com a marca na página 1. Se a estilização do próprio livro de marca não passar nas regras que prega, está errado.

7. Primeiro sistema, depois alternância para modo escuro. Respeite prefers-color-scheme por padrão; persista substituições explícitas do usuário em localStorage. Um alternador visível de modo escuro na navegação é um antipadrão. A regra do favicon SVG consciente do sistema em reference/favicon-pack.md segue a mesma lógica.

Não-objetivos

• Gerar arte do logotipo — isso é image-generation.
• Pipelines de recursos mecânicos (vetorizar PNG → SVG, geração de pacote de ícones, rasterizar em tamanho) — isso é brand-assets.
• Construir os componentes reais — §18 de BRAND.md documenta as especificações; react-components e frontend-design os implementam.
• Redação de storytelling / copywriting de marketing — §13 rege como escrever, não o quê.
• Traduzir texto — a habilidade cria estrutura consciente de RTL, mas não traduz.
• Versionar o livro de marca como um produto — atualize no local, confirme com uma mensagem clara, uma única fonte da verdade na raiz do repositório.

Sumário canônico de 20 seções (o que BRAND.md.tmpl emite)

#	Seção	Essencial obrigatório
0	A ideia	Ideia central em uma frase + o teste "remova tudo menos X"
1	Lendo a marca	3–5 leituras simultâneas do logotipo
2	Primitiva de assinatura	O token semântico que aparece em cada superfície — 8+ locais de uso
3	Movimentos de assinatura	5–7 coisas que identificam a marca sem o logotipo
4	Essência da marca	O que somos / não somos / tom / frase de posicionamento
5	Sistema de logotipo	Variantes, espaço livre, tamanho mínimo, não faça, requisitos de favicon + pacote PWA
6	Sistema de cor	Núcleo + estendido + neutros + tokens semânticos, proporção 62/30/8, paridade claro/escuro
7	Tipografia	Face, números tabulares, escala, medida, movimentos RTL, tratamento de wordmark
8	Iconografia	Estilo, regras de cor (acento nunca usado), tokens de tamanho, espelhamento RTL
9	Espaçamento e layout	Grade de 8 pontos, contêineres, raios + regra de raios concêntricos
10	Superfícies e materiais	Material padrão + flutuante, sobreposição de grão, fundos de herói
11	Movimento	Princípio, tokens, animação de assinatura, comportamento de movimento reduzido
12	Imagens e ilustração	Regras de fotografia, estilo de ilustração, antipadrões
13	Voz e tom	Regras, matriz de tom por estado emocional, 3 níveis do mesmo pensamento, especificidades RTL
14	Acessibilidade	Matriz de contraste WCAG 2.2 AA, anéis de foco, movimento reduzido, equivalência RTL
15	Conjunto de referência	Em qual prateleira a marca se senta + o que ela não é
16	Antipadrões	Lista específica de "não faça isso" — maus hábitos concretos banidos
17	Implementação — Tailwind v4 @theme	Bloco completo, :root + [data-theme="dark"], regras do corpo
18	Componentes	Botões, links, entradas, cartões, badges, navegação, alertas, diálogos, prosa, primitivas de landing
19	Plano de migração	O que está sendo aposentado; ✅/⚠️/❌ por token/padrão; datas
20	O que isso não é + Registro de decisões	Não-objetivos + tabela datada de decisões com justificativa

Invocação rápida

# Crie um novo livro de marca na raiz do repositório
~/.claude/skills/brand-system/scripts/new-brand-book.sh \
  --product "Agentiko" \
  --positioning "Um trabalhador real que vive dentro do WhatsApp." \
  --palette-bg '#F3EAD3' \
  --palette-fg '#0E1320' \
  --palette-accent '#B85A3A' \
  --signature-primitive "ponto de voz" \
  --primary-font "Rubik" \
  --locale "he" \
  --output-dir .

# Auditar contraste
~/.claude/skills/brand-system/scripts/audit-contrast.py \
  --bg '#F3EAD3' --fg '#0E1320' --accent '#B85A3A'

# Renderizar o imprimível
~/.claude/skills/brand-system/scripts/render-pdf.sh BRAND.html BRAND.pdf

# Depois: verificar um livro existente contra o sumário
~/.claude/skills/brand-system/scripts/audit-outline.py BRAND.md

Habilidades relacionadas

• brand-assets — pipelines mecânicos de SVG/PNG; execute após esta habilidade para produzir o pacote de favicon.
• image-generation — projete imagens de logotipo/herói antes de executar esta habilidade.
• frontend-design — implemente os componentes da §18 em código de produção.
• react-components — construa primitivas de componente uma vez que a §18 esteja criada.