brandvm/Guia-de-Estilo-Webflow

Guia de estilo Webflow: um layout, todos os sites

O guia de estilo é a primeira página construída no protótipo e a primeira página construída no Webflow, antes de qualquer outra página. Ele valida as variáveis, estilos de tags e classes antes que qualquer coisa dependa deles, e contém toda classe em um elemento, para que o recurso Limpar estilos não utilizados do Webflow nunca possa excluir uma classe que apenas o CMS, um script ou uma página não construída use.

Seu layout é fixo. Um projeto fornece conteúdo, nunca layout:

• sg.css é o layout da própria página (as classes Sg).
• scripts/gen-style-guide.mjs escreve a página a partir do snapshot do Webflow, do CSS e dos espécimes do projeto.
• scripts/check-style-guide.mjs falha quando uma classe está faltando na página, as classes de uma combinação nunca aparecem juntas em um elemento, ou o layout se desviou.
• scripts/sections.mjs é a lista de seções que ambos os scripts compartilham.
• Cada espécime de tipografia carrega data-sg-type (seu nome), para que o pnpm measure:type do protótipo possa imprimir o tipo como renderizado em 1440 e 390 (tamanho, altura da linha, espaçamento, peso) para comparar com a ficha de tipos do design antes que as classes sejam inseridas no Webflow.

As regras compartilhadas se aplicam (webflow-build › rules.md: Designer primeiro, nenhum commit ou push sem OK), e no Webflow as regras da própria construção: um sinal verde antes de cada lote.

O layout

Moldura. Uma barra lateral fixa à esquerda lista as seções, numeradas, como links para elas; a seção sendo lida é destacada. Uma coluna de conteúdo à direita. Em 991px e abaixo, a barra lateral se torna uma faixa de links abaixo da navegação que rola horizontalmente.

Escrito para alguém novo. A página precisa fazer sentido para uma pessoa que nunca viu o site: um cliente, ou um desenvolvedor em seu primeiro dia.

• Visão Geral abre com o que é a página, quatro cards sobre como usá-la (encontrá-la, ler uma linha, reutilizar antes de adicionar, adicionar aqui), o site de relance (contagens), suas fontes, suas coleções de variáveis e os breakpoints.
• Cada seção começa com seu número, seu título e uma linha dizendo para que serve e como usá-la (o texto está em scripts/sections.mjs, o mesmo em todos os sites).
• Espécimes de botões, formulários e componentes ficam em um painel; nomes de classes ficam em um chip; tabelas longas mantêm seu nome visível enquanto rolam.
• Cada rótulo usa a fonte do próprio site. Sem monoespaçada: uma classe Designer contém uma família de fontes, e uma fonte monoespaçada do sistema traz seu próprio zero cortado.
• A moldura usa as cores da página (linhas e painéis neutros com baixa opacidade), para parecer igual em um site claro ou escuro.

Seções, sempre nesta ordem, com estes nomes e ids. Uma seção sem nada é omitida; nada é adicionado, renomeado ou reordenado.

#	Seção	id	Origem
1	Visão Geral	overview	gerado: como usar a página, contagens, fontes, coleções, breakpoints
2	Cores	colors	toda variável de Cor fora de Cores Semânticas
3	Temas	themes	Seção, toda classe que define um modo de Cores Semânticas, e a tabela de papéis por modo
4	Tipografia	typography	toda classe que define um modo de Estilos de Tipografia, os estilos de tag nativos (cabeçalhos, parágrafos, links), os recursos de fonte do estilo Body e a escala tipográfica
5	Utilitários	utilities	classes de Tamanho, Peso, Entrelinha, Rastreamento, Texto e Largura Máxima
6	Espaçamento, raio e layout	spacing	as variáveis de Espaçamento (cada um com uma barra de seu tamanho), Raio e Layout
7	Botões e links	buttons	espécimes
8	Formulários	form-elements	espécimes (itens usam section=forms; Webflow recusa forms como id de elemento)
9	Componentes	components	espécimes
10	Seções de página	page-sections	espécimes, mostrados em meia tela
11	Outras classes	other-classes	gerado: toda classe que nada acima se aplica

A linha. Cada item na página é um Sg Row: à esquerda seu nome como o Designer mostra, sua classe CSS, e uma nota em palavras simples (a que ele se liga, seus valores por breakpoint, seus estados); à direita, o espécime vivo. Uma seção é um cabeçalho e uma lista de linhas. Tabelas de valores (papéis por modo, escala tipográfica, espaçamento, layout) ficam no espécime de uma linha como um Sg Table: a coluna de nome, depois uma coluna por modo ou valor.

Nenhuma classe de projeto na moldura. A moldura usa apenas classes Sg, para que a página pareça a mesma independentemente da escala tipográfica ou do preenchimento de seção de um projeto. Classes de projeto aparecem nos espécimes.

Variáveis são um padrão, não um limite

A página mostra o que o site tiver. As coleções, nomes e valores iniciais do modelo (convenções webflow-build §4, incluindo Geist como a fonte padrão) são o layout padrão e a forma de usar variáveis; um projeto é livre para alterar valores e adicionar, renomear ou remover variáveis, modos e coleções.

• Qualquer variável de Cor fora da coleção semântica é uma amostra; qualquer classe que define um modo é uma linha de tema ou tipo; qualquer coleção que o gerador não conhece por papel é mostrada como uma tabela em “Espaçamento, raio e layout”.
• Um site que nomeia as coleções padrão de forma diferente informa isso em design/style-guide/config.json, por exemplo { "collections": { "semantic": "Themes", "typeStyles": "Type Styles" } } (chaves: semantic, typeStyles, typeRole, typeScale, spacing, radius, layout).
• O que permanece fixo é o layout: a moldura, a ordem das seções, a linha.

Espécimes (seções 7 a 10)

Duas maneiras de fornecê-los; ambas produzem a mesma linha.

1. De uma página real, para que permaneça sincronizado com ela. Envolva a marcação na página:

<!-- sg:start section=components | name=Card | class=.card | note=Usado em listas e na página inicial -->
<a class="card" href="/work/item" data-card>…</a>
<!-- sg:end -->

2. Manualmente, para o que nenhuma página mostra por conta própria (estados de botões, partes de formulário). Um arquivo por seção em design/style-guide/items/, cada item um comentário de cabeçalho seguido por sua marcação:

<!-- sg: section=buttons | name=Button Is Secondary | class=.button.is-secondary | note=Combinação em Button -->
<a class="button is-secondary" href="#buttons">Secondary</a>

• section é buttons, forms, components ou page-sections; name é obrigatório; class e note são opcionais.
• Prefira um bloco de página real para componentes e seções de página. Um espécime copiado manualmente se desvia da página, e em construções anteriores componentes construídos a partir de pré-visualizações copiadas manualmente perderam seus hooks de script.
• O gerador remove ids, for, hooks data-* e referências a id de um espécime e o marca como inert: é uma imagem do componente, não uma cópia funcional, então nenhum script anexa e nada nele recebe foco.
• A página é noindex, então um segundo h1 nela é aceitável: a seção Tipografia mostra um real como espécime do estilo de tag All H1 Headings, e um espécime pode conter um.
• Um espécime page-sections é mostrado na metade do tamanho em um quadro selado. Remova-o assim que sua página existir no Webflow: a página então mantém suas classes. Seções 1 a 9 permanecem permanentemente.
• Nenhum atributo style inline: o importador do Webflow transforma cada um em uma classe de combinação lixo. Amostras de cor, caixas de raio e barras de espaçamento usam uma combinação gerada por variável.

No protótipo (primeira página)

1. A pasta do protótipo existe (webflow-prototype › Project setup) e seu snapshot do Webflow está atualizado (pnpm css).
2. pnpm style-guide. Ele escreve design/style-guide/index.html e src/css/style-guide.css. Nunca edite nenhum dos dois.
3. Adicione os espécimes do projeto (itens de botão e formulário; blocos de componente e página conforme as páginas são construídas) e execute novamente.
4. pnpm check:style-guide até passar.
5. A pessoa revisa a página em 1440, 820, 667 e 390 e a aprova antes que a primeira página de conteúdo seja iniciada.
6. A partir daí, toda nova classe ou componente ganha sua linha no mesmo trabalho: adicione o espécime, pnpm style-guide, pnpm check:style-guide.

No Webflow (primeira página)

Após variáveis, estilos de tag, classes e o bundle do repositório estarem presentes, e antes de qualquer outra página. Um sinal verde por lote.

1. Página. /design/style-guide na pasta design, no shell padrão (webflow-build convenções §1). noindex, nofollow no código da página; excluída da pesquisa do site e do sitemap (a configuração do sitemap precisa de um plano de site: em um site sem um, a tag noindex é o que a mantém fora da pesquisa, e a exclusão é definida assim que o plano existir); links para ela fazem um carregamento de página completo.
2. Classes Sg. Um site duplicado a partir do iniciador já as possui. Caso contrário, a maneira mais rápida que mantém cada valor: importe a moldura com o construtor WHTML e passe sg.css como seu css (variáveis e calc() substituídas por valores simples, rgb(r g b / a) escrito como rgba()). O importador cria cada classe com propriedades expandidas, estados e breakpoints, nomeada por seu slug; renomeie cada uma depois para o nome que o Designer deve mostrar (Sg Row, Sg Row Meta, Sg Table Key…). As regras .w--current se tornam o estado Current de Sg Sidebar Link, que a própria ferramenta de estilo não pode escrever. Isso só funciona enquanto a classe é nova: para uma classe que já existe, o importador cria uma duplicata numerada (webflow-build/lessons/mcp.md).
3. Combinações de variáveis. Para cada variável de cor, a combinação Sg Swatch Color + Is … vinculando background-color; para cada variável de raio, Sg Radius + Is … vinculando border-radius; para cada variável de espaçamento, Sg Bar + Is … vinculando width. O gerado src/css/style-guide.css as lista, uma por linha.
4. Construa seção por seção a partir da página gerada, apenas com classes. Crie cada classe e combinação antes de importar a marcação (o importador descarta uma lista de classes inteira se uma classe estiver faltando). Em seguida, aponte cada link da barra lateral para sua seção (tipo de link: seção da página), para que o Webflow marque a atual.
5. Linhas para componentes são instâncias de componente, não cópias de sua marcação.
6. Verifique em staging: toda classe no site aparece na página publicada ou no shell, e toda combinação em um elemento (uma combinação cujas classes só aparecem separadas ainda é excluída pela limpeza); a barra lateral destaca a seção em vista; noindex está no . Só então Limpar estilos não utilizados é seguro.

Em um site existente

Um site não construído a partir do modelo pode obter a mesma página: crie uma pasta de protótipo a partir do iniciador de protótipo da skill webflow-prototype, tire o snapshot do site e siga “No protótipo” e “No Webflow”. Suas classes Sg ainda não existirão; crie-as na etapa 2.

Gates

• Guia de estilo do protótipo aprovado [Pessoa]: antes da primeira página de conteúdo do protótipo.
• Base do guia de estilo concluída [Claude verifica, Pessoa aprova]: a página do Webflow contém toda classe existente até o momento; publicada e verificada em três larguras.
• Verificação final do guia de estilo [Claude verifica]: na entrega da construção, pnpm check:style-guide passa e a página publicada contém toda classe.

Alterando o layout

O layout muda aqui, para todos os sites de uma vez, nunca em um projeto: edite sg.css, a lista de seções ou o gerador no modelo, atualize o site iniciador no mesmo ciclo de trabalho e publique a atualização (webflow-build › rules.md › Contributing). Os projetos recebem a atualização com pnpm update-skills e pnpm style-guide.