O que Sistema de Design Atômico MarketingOS faz?
Transforma uma marca em um sistema de design revisável: tokens em camadas, um arquivo de especificação por componente, e um site de referência HTML estático, construído um degrau por vez com aprovação humana entre cada etapa — tudo sob uma única pasta design-system/ que uma pessoa ou agente pode navegar a partir de um único README.
Contexto e pré-requisitos do MarketingOS
Resolva o cérebro de negócios ativo e o alvo do website da sessão atual e seus registros de projeto. Leia o BRAIN.md do cérebro ou as instruções do agente, CONTEXT.md, marca, voz, público, oferta e referências de design salvas antes de solicitar informações. Mantenha o contexto de cada negócio separado. Registre o cérebro fonte e o alvo no briefing de design. Quando usado sem o MarketingOS, trabalhe a partir dos arquivos de marca fornecidos e identifique lacunas genuínas.
Use o Bun para os scripts TypeScript agrupados. Se estiver faltando, guie o usuário para as instruções oficiais de instalação em https://bun.com/docs/installation. Resolva $SKILL para o diretório real que contém este SKILL.md carregado; os agentes instalam em lugares diferentes, então não presuma um caminho de instalação específico.
Se o usuário tiver selecionado o Taste Skill, leia suas instruções instaladas primeiro e use suas diretrizes de arte e descobertas de referência como entradas para este framework. Preserve o contrato de marca, sistema de tokens e decisões de estágio deste framework. O Taste Skill é uma dependência opcional separada, não incluída neste pacote; inspecione suas instruções oficiais atuais em https://github.com/leonxlnx/taste-skill quando a instalação for solicitada.
Um único prompt inicial pode direcionar o fluxo de trabalho completo. Mantenha as decisões necessárias e aprovações de estágio visual na mesma conversa, retomando após cada resposta sem exigir outro prompt copiado e colado. Pare no estágio que o usuário solicitou; não trate a invocação como permissão para pular aprovações.
A ideia
Um sistema de design falha de duas maneiras. Ou ele é inventado — o modelo escolhe uma paleta bonita e o resultado é confiante, coerente, e não é a marca. Ou é construído de uma vez, então uma decisão errada na base propaga-se silenciosamente por vinte páginas antes que alguém a veja.
Este skill aborda ambos. Descoberta antes do design: encontre o que já foi decidido e seja explícito sobre as lacunas. Um portão entre os degraus: retrabalhar nos Fundamentos é uma edição de cinco linhas; o mesmo retrabalho nas Páginas são vinte páginas.
Roteador
Descubra onde o usuário está e então aja. Não pergunte qual modo eles querem.
| Situação | Faça isso |
|---|---|
Nenhum STATE.json e a descoberta não encontra sistema atômico existente | Inicie o Estágio 0 (layout v2) |
A descoberta relata existingAtomicSystem mas não há STATE.json (HTML feito à mão, por exemplo, public/atomic-framework/ de um projeto existente, stage-*.html de um projeto legado) | Sistema legado. Estenda-o em seus próprios arquivos e nomenclatura: adicione às suas páginas existentes, mantenha suas convenções de marcação/classe/ID, registre o novo trabalho em um pequeno ATOMIC-NOTES.md ao lado. Suas convenções são mantidas, mas o piso de qualidade não é reduzido: :focus-visible visível, alvos de 44px, contraste, e um Mapa de Inspiração com itens de aceitar e deixar preenchidos. Se viver em um repositório irmão, esse é um segundo repositório — pergunte antes de escrever lá (veja Segurança) e dê ao alvo um pequeno DESIGN-SYSTEM.md apontando para ele. Não crie scaffold v2 a menos que o usuário peça para migrar. Verifique com verify-stage.ts --legacy <dir>. Detalhe: references/output-structure.md |
design-system/STATE.json com schemaVersion: 2 | Sistema v2: relate o status, execute o próximo estágio não aprovado |
STATE.json sem schemaVersion: 2 (em docs/design-system/ ou design-system/docs/) | Sistema v1 construído pelo skill antigo. Estenda-o no layout e convenções v1 (init-system.ts --schema 1 se um arquivo de scaffold v1 estiver faltando). Não migre a menos que o usuário peça |
| "migrar para v2" / "mover para a nova estrutura" | Siga o procedimento de migração em references/output-structure.md, em um branch |
"refazer as moléculas" (ou --stage <n> na solicitação) | Reconstrua aquele estágio, marque os downstream como desatualizados |
"onde estamos" (ou --status) | Imprima a escada com status e versão por estágio, então pare |
| "exportar para figma" / "variáveis figma" | Execute export-figma.ts — veja references/figma-export.md. Nunca faz parte da escada |
Usuário explicitamente renuncia aos portões ("não pare para aprovações"; --non-interactive em uma avaliação ou CI) | Execute a escada sem parar e apresente todos os portões juntos no final — veja "Aprovações Renunciadas" abaixo |
| Repositório alvo incerto | Pergunte, uma vez. Não adivinhe entre repositórios irmãos |
Resolva o repositório alvo primeiro. Todo o resto é relativo a ele.
--stage, --status e --non-interactive acima são maneiras como um usuário formula uma solicitação para este skill — modos de comportamento, não flags de script.
Configuração
# Defina SKILL para o diretório real que contém o SKILL.md carregado
bun $SKILL/scripts/discover-brand.ts --target <repo> [--siblings <dir>] # Estágio 0
bun $SKILL/scripts/init-system.ts --target <repo> # scaffold v2; --schema 1 apenas para sistema v1 do skill antigo
bun $SKILL/scripts/init-system.ts --target <repo> --page <file> # prepara a página do shell, trilho + aria-current preenchidos
bun $SKILL/scripts/verify-stage.ts --target <repo> --stage <n> # lê schemaVersion; --legacy <dir> para sistemas feitos à mão
bun $SKILL/scripts/build-index.ts --target <repo> # após cada estágio aprovado
bun $SKILL/scripts/export-tokens.ts --target <repo> # tokens.css → tokens.json + TOKENS.md (build-index o executa)
bun $SKILL/scripts/export-figma.ts --target <repo> # opcional
discover-brand.ts pesquisa o alvo e seu diretório pai por padrão. Use --siblings <dir> quando o cérebro ativo residir em outro lugar. Leia o cérebro resolvido explicitamente mesmo quando a descoberta não encontrar nenhum irmão correspondente. Cada flag de script está documentada em references/output-structure.md.
Saída (v2) — uma raiz, um arquivo de entrada, uma especificação por componente:
design-system/
├── README.md COMECE AQUI — ponto de entrada para pessoas e agentes
├── STATE.json schemaVersion 2, estágios, aprovações, inventário, versão, temas
├── CHANGELOG.md uma entrada por estágio aprovado / publicação
├── brief/DESIGN-BRIEF.md
├── tokens/ tokens.css (canônico) · tokens.json · TOKENS.md (gerado) · figma/ (opcional)
├── foundations/FOUNDATIONS.md
├── components/ INDEX.md (gerado) · atoms/ molecules/ organisms/ templates/ <ID>-<slug>.md
├── rules/RULES.md
└── reference/ site de revisão HTML estático (noindex) · styles.css · pages/P-nn-<slug>.html
Por que é moldado dessa forma, a especificação do README, a tabela de caminho v1 → v2 e o procedimento de migração: references/output-structure.md. Leia ao fazer scaffold, escrever o README ou migrar.
A escada
Sete estágios de construção. Fundamentos fica à frente de Átomos porque não se pode construir um átomo sem tokens; Regras fica por último porque as salvaguardas são escritas a partir do que foi realmente decidido. Os caminhos são relativos a design-system/.
| # | Estágio | Produz |
|---|---|---|
| 0 | Descobrir | brief/DESIGN-BRIEF.md, STATE.json, esqueleto README.md, CHANGELOG.md, reference/index.html (00) |
| 1 | Fundamentos | tokens/tokens.css (+ json/md gerados), foundations/FOUNDATIONS.md, reference/foundations.html (01) |
| 2 | Átomos | components/atoms/A-nn-*.md, reference/atoms.html (02), reference/icons.html (02A) |
| 3 | Moléculas | components/molecules/M-nn-*.md, reference/molecules.html (03) |
| 4 | Organismos | components/organisms/O-nn-*.md, reference/organisms.html (04) |
| 5 | Templates | components/templates/T-nn-*.md, reference/templates.html (05) |
| 6 | Páginas | reference/pages.html (06), reference/pages/P-nn-*.html, reference/rules.html (07), rules/RULES.md, README.md final, versão 1.0.0 |
Artefatos completos por estágio e critérios de aceitação: references/stage-specs.md. Leia a seção do estágio em que você está, não o arquivo inteiro.
Estágio 0 — Descobrir
Três entradas, depois síntese. Faça as duas primeiras concorrentemente; elas não dependem uma da outra.
1. Inspiração de design. Reutilize referências salvas do cérebro ativo ou da passagem do Taste Skill primeiro; peça apenas URLs brutas faltantes — três a seis, páginas específicas em vez de homepages quando possível. Capture cada uma com a ferramenta de navegador disponível, verificando fontes e layout reais. Use o Interceptor apenas se estiver instalado e for apropriado para a sessão. Extraia a paleta computada, pilha de tipografia, ritmo de espaçamento e raios — valores renderizados reais, não hexadecimais de marketing.
2. Mobbin MCP (opcional). Para perguntas de padrão que as URLs não podem responder: como esta categoria sequencia a integração, estrutura preços, lida com estados vazios. O MCP pode estar instalado mas não autenticado — se apenas mcp__mobbin__authenticate / complete_authentication estiverem expostos, execute o fluxo OAuth e entregue a URL ao usuário. Se eles recusarem, continue e registre a lacuna no briefing. Nunca implique que a pesquisa de padrões ocorreu quando não ocorreu.
3. Descoberta de marca. Execute discover-brand.ts. Ele sonda as convenções de caminho conhecidas através do alvo e seus repositórios irmãos, mescla documentos complementares e particiona por família de marca antes de classificar — para que um documento polido de outra marca nunca possa vencer. Leia três coisas: qual documento, se o contrato visual é full/partial/verbal-only, e se um sistema atômico já existe (se sim, estenda-o em vez de começar do zero).
Confirme a fonte da marca com o usuário antes de compilar qualquer coisa. É o único erro que invalida todos os estágios downstream.
Em seguida, escreva DESIGN-BRIEF.md. Seu Mapa de Inspiração precisa de ambas as metades de cada linha — o que aceitamos e o que deliberadamente deixamos. A coluna de deixar é onde o julgamento reside; uma linha com apenas "aceitar" é uma instrução de colagem. Seu §3 contrato visual nomeia cada matiz e o passo que cada hex dado ocupa, os temas e a proporção da escala tipográfica — as entradas que o Estágio 1 compila.
Detalhe: references/brand-discovery.md e references/inspiration-research.md.
Estágios 1–6 — o ciclo
Cada estágio executa as mesmas cinco batidas.
1. Construir. Siga a especificação do estágio. Componha apenas peças de nível inferior aprovadas. Um estágio que precisa de um token que Fundamentos não tem significa que Fundamentos estava incompleto — volte e emende-o em vez de definir um valor local, ou o sistema começará a se contradizer. Estágio 1: leia references/token-architecture.md primeiro. Estágios 2–4: leia references/component-anatomy.md primeiro, e escreva um arquivo de especificação por componente de assets/docs/COMPONENT-SPEC.md junto com seu espécime. O Estágio 1 também executa export-tokens.ts para que tokens.json e TOKENS.md existam para a revisão. Inicie a página de cada estágio com init-system.ts --page <file> para que o trilho seja gerado, não copiado à mão.
2. Verificar. bun $SKILL/scripts/verify-stage.ts --target <repo> --stage <n>. Corrija o que ele relata antes de mostrar qualquer coisa. Ele verifica contiguidade de IDs, valores brutos fora de tokens.css, marcadores de camada e referências de camada, tratamentos de foco, noindex, fiação do trilho, receitas de organismos e ordenação de estados.
3. Mostrar. Olhe para a página renderizada antes do revisor, nesta ordem: a ferramenta de navegador disponível da sessão sobre HTTP local, com fontes carregadas → outra ferramenta de navegador visual disponível → apenas verificações de DOM (tokens computados, fontes carregadas, sem rolagem lateral a 375px). Headless perde fontes web e problemas de renderização, que são grande parte do que está sendo julgado. Diga qual camada você usou e o que não foi verificado visualmente.
4. Portão. Apresente o artefato e pergunte usando a ferramenta de perguntas disponível ou uma mensagem concisa:
- Aprovar → avance
STATE.json, desbloqueie o próximo estágio - Revisar → anote as observações, reconstrua, verifique, mostre novamente
- Aprovar com notas → avance, registre as notas como decisões em aberto
Avançar apenas em um sim explícito. O portão existe porque o revisor sabe coisas sobre esta marca que não estão escritas em lugar nenhum — e porque é o acelerador que permite que uma grande construção pare após Átomos e seja retomada na próxima semana.
Aprovações Renunciadas. Quando o usuário explicitamente diz para não parar (ou uma avaliação ou prompt de CI é executado de forma não interativa), execute a escada sem pausar: responda à entrevista do Estágio 0 a partir da solicitação e das evidências, marque cada resposta como provisória nas decisões em aberto do briefing, registre cada estágio como "aprovado sem revisão (renunciado pelo usuário)" em STATE.json e CHANGELOG.md, e apresente todos os portões juntos no final. Nunca renuncie por seu próprio julgamento — um usuário quieto não renunciou a nada. Detalhe: references/stage-specs.md.
5. Indexar. Após a aprovação: marque as especificações do estágio como status: approved, execute build-index.ts (regenera tokens.json, TOKENS.md, components/INDEX.md e o índice de arquivos README), anexe uma entrada CHANGELOG.md listando apenas o que mudou, e aumente STATE.json version — 0.1.0 para Fundamentos até 0.5.0 para Templates; aprovar Páginas publica 1.0.0. Alterar um estágio aprovado é um patch (assim como re-aprovar cada estágio downstream desatualizado); regras completas em references/output-structure.md. Arquivos gerados carregam um cabeçalho de não editar à mão; edite suas fontes e execute novamente.
Quando você apresentar um estágio, mantenha-o curto: o que foi construído, a contagem por nível, qualquer coisa que você teve que decidir sem evidência, e a única coisa que mais vale a pena olhar. Não é um tour por cada espécime.
Convenções que valem em toda parte
Detalhe completo em references/html-conventions.md. As essenciais:
- IDs contíguos com zero à esquerda —
A-01,M-17,O-04,T-05,P-02— mostrados na UI via.card-label, espelhados emdata-*, e correspondendo ao nome do arquivo de especificação. Estáveis após aprovação; renumerar quebra todas as referências. - Quatro camadas de token — marca → alias → mapeado → responsivo, cada uma aberta por um marcador
@tieremtokens.css. Literais brutos apenas em Marca e Responsivo. Cor, largura de borda e raio vão Mapeado → Alias → Marca, nunca pulando;--space-*,--duration-*,--ease-*,--shadomapeados