Communitygithub.com

Sistema de Design Atômico MarketingOS

Construa ou estenda um sistema de design atômico baseado em marca com tokens, especificações de componentes e um site de revisão HTML. Use para sistemas de design, kits de UI, bibliotecas de componentes, trabalho de marca para token e exportações de tokens do Figma. Funciona a partir de um cérebro ativo do MarketingOS ou de arquivos de marca independentes; preserva sistemas existentes e aprovações de estágio.

O que é Sistema de Design Atômico MarketingOS?

O Skill de Sistema de Design Atômico do MarketingOS transforma uma marca em um sistema de design revisável e escalável, completo com tokens organizados em camadas, especificações de componentes e um site de referência estático em HTML. Ele é projetado para desenvolvedores e agentes de IA que precisam construir ou estender sistemas de design de forma sistemática, garantindo que cada decisão seja aprovada antes de passar para o próximo estágio, evitando a propagação de erros. O skill suporta plataformas como Claude Code, Cursor e Codex, e funciona tanto integrado ao cérebro ativo do MarketingOS quanto com arquivos de marca independentes. Ele implementa um fluxo de trabalho em sete estágios (Descoberta, Fundamentos, Átomos, Moléculas, Organismos, Templates e Páginas), com verificações de verificação e portões de aprovação explícitos entre cada estágio, além de oferecer suporte a exportação para Figma e integração opcional com o Taste Skill para direção de arte.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/the-vibe-marketing-lab/mos-design-skills/tree/HEAD/mos-atomic-design-system

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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çãoFaça isso
Nenhum STATE.json e a descoberta não encontra sistema atômico existenteInicie 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: 2Sistema 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 incertoPergunte, 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ágioProduz
0Descobrirbrief/DESIGN-BRIEF.md, STATE.json, esqueleto README.md, CHANGELOG.md, reference/index.html (00)
1Fundamentostokens/tokens.css (+ json/md gerados), foundations/FOUNDATIONS.md, reference/foundations.html (01)
2Átomoscomponents/atoms/A-nn-*.md, reference/atoms.html (02), reference/icons.html (02A)
3Moléculascomponents/molecules/M-nn-*.md, reference/molecules.html (03)
4Organismoscomponents/organisms/O-nn-*.md, reference/organisms.html (04)
5Templatescomponents/templates/T-nn-*.md, reference/templates.html (05)
6Páginasreference/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 em data-*, 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 @tier em tokens.css. Literais brutos apenas em Marca e Responsivo. Cor, largura de borda e raio vão Mapeado → Alias → Marca, nunca pulando; --space-*, --duration-*, --ease-*, --shado mapeados

Habilidades Relacionadas