YLynnLee/reference-to-style

Referência para estilo

Transforma referências em um estilo para todo o site, exibido em um painel visual (board.html) e respaldado por um guia de estilo medido (style.md). A aparência vem das referências; o conteúdo vem do assunto. Definir um estilo nunca altera o app ou site. Aplicar um estilo altera, mas apenas quando o usuário nomeia um estilo salvo para usar (veja Aplicando um estilo salvo).

Alinhe o estilo uma vez, antes de qualquer alteração na página. O guia é a fonte da verdade: construa cada elemento visual a partir dele e coloque toda correção nele primeiro, para que nada construído a partir dele possa se desviar do que você viu no painel.

Meça, não confie na intuição. A visão é boa para ver o que uma referência faz e ruim para cores, tamanhos e espaçamentos exatos. Todo valor que uma referência mostra vem de scripts/measure.py (qualquer outra coisa é derivada desses ou escolhida, e assim declarado), e toda amostra do painel é renderizada e medida da mesma forma por scripts/verify.py até corresponder. O painel permanece visual; os números ficam no guia e no relatório.

Comece sutil, depois ajuste. Uma referência é seu estilo em concentração total, e espalhar cada traço sobre todo elemento pode exagerar. Então a primeira passagem usa cada traço distintivo apenas onde ele faz mais trabalho, com seus valores medidos, e o usuário ajusta traços individuais para cima ou para baixo na revisão. A intensidade muda onde um traço aparece, nunca seus valores medidos.

Quando não usar

• O usuário quer uma correspondência exata com seu próprio frame do Figma. Construa o frame.
• O projeto já tem um estilo salvo em design/styles/. Aplique-o em vez disso (veja Aplicando um estilo salvo).

Pré-requisitos

Antes do passo 1, execute python3 <este skill>/scripts/doctor.py (no Windows, use py -3 no lugar de python3 em todo o processo). Ele verifica todas as dependências e imprime o comando de instalação exato para cada uma ausente.

• Código de saída 0: pronto.
• Código de saída 1: pacotes Python ausentes. Mostre ao usuário os comandos impressos e aguarde; nada pode ser medido sem eles.
• Código de saída 2: o navegador não pode ser executado. Ofereça os comandos de instalação impressos. Se o usuário não puder instalar, prossiga apenas com referências de imagem (peça capturas de tela de sites ao vivo), execute check.py com --unverified e diga na revisão que a precisão do painel não está comprovada.
• Sem Python (python3 não encontrado, nem py -3 no Windows): doctor.py não pode ser executado. Diga ao usuário que o skill precisa de Python 3.9 ou superior, de python.org ou do gerenciador de pacotes do sistema, e aguarde. Não instale Python você mesmo.

Decisões

Tome todas as decisões que a execução precisar você mesmo, e pare somente quando: no painel. O painel mostra ao usuário o estilo completo de relance, para que ele julgue ali, não como uma lista de perguntas antecipadas.

• Decida, não pergunte: quais traços adotar ou deixar, a intensidade inicial de cada um, o nome e o slug do estilo, a lista de assuntos, a direção quando as referências concordam e como evitar conflitos com um estilo existente. Registre cada escolha no guia (uma fonte chosen: ou uma linha Adotar/Deixar), para que possa ser alterada depois.
• Pergunte cedo apenas quando não puder prosseguir: uma referência não carrega ou é apenas uma miniatura, uma dependência está faltando, ou as referências apontam para direções opostas (como papel de desenho pálido e planta escura) que nem elas nem o projeto resolvem. Então faça uma pergunta curta com as opções, sua escolha primeiro, e nada mais.
• Mantenha a parada curta. Os números vivem no guia e em verify.md, então a mensagem não carrega tabelas ou medidas. Termine com este bloco, depois aguarde:

Sua opinião: algo a mudar?

Painel: <caminho para board.html> · Precisão: 35 de 35 medições correspondem (verify.md) Decidido para você: nome e slug; os principais traços adotados e deixados; a direção, se houve escolha Começou sutil: cada traço sutil e onde aparece, em poucas palavras

1. Ajustar um traço para cima ou para baixo: nomeie-o, como "mais da grade" ou "menos vermelho"
2. Mudar outra coisa: diga o quê
3. Nada: o estilo é salvo como está

Usando: o estilo está salvo em design/styles/<slug>/. Nomeie-o quando quiser usá-lo, como "aplicar <slug> em tudo". Até lá o app ou site não muda.

Com uma ferramenta de pergunta, faça-a também ali, começando com "Sua opinião". Nada precisa de aprovação: todo estilo salvo está pronto para uso, e o usuário escolhe um pelo nome depois.

Passos

1. Veja as referências, depois meça-as. Abra cada uma: role sites ao vivo e observe seu movimento. Se uma não carregar ou for apenas uma miniatura, peça uma captura de tela. Nunca trabalhe a partir de um título ou URL. Salve uma captura de tela de cada uma em references/ e anote qualquer movimento observado. Prefira PNG: JPEG acinza linhas coloridas finas.

   Em seguida, leia references/measure.md e meça um recorte por traço que você possa adotar (um título, um botão, uma régua, uma área de fundo), tudo em uma única execução.

2. Leia o projeto. Faça isso antes de escolher um estilo, para que a direção já se encaixe:

   • Leia design/styles/index.md se existir, para que o novo estilo não conflite com os anteriores, e anote quais slugs já estão em uso.
   • Liste de 4 a 8 objetos, materiais, processos, medidas ou lugares reais, cada um com sua fonte. Comece pela lista de assuntos compartilhados do índice. Use coisas reais, não símbolos do tópico, e deixe de fora qualquer coisa que não possa ter fonte.
   • Encontre os tokens do site (propriedades customizadas CSS, classes do framework ou variáveis do Webflow) e cada tipo de componente em uso, como títulos, botões, cards, figuras, linhas de lista, navegação e formulários, com onde cada um vive. O guia reformata sua aparência; seu conteúdo e estrutura permanecem.

3. Leia o estilo. Com várias referências, leia o que elas compartilham. Vincule cada traço ao recorte que o mostra; essa evidência vai para o guia, não para o chat.

   Adotar: o estilo	Deixar: o que pertence a uma referência
   Paleta, caráter tipográfico, linha e forma, superfície, densidade, ritmo, hierarquia, movimento	Ativos, logotipos, cópia, layouts de página exatos, detalhes pontuais

   Atribua a cada traço Adotado uma intensidade, escrita na coluna Intensidade do guia:

   Intensidade	Onde o traço aparece	Usado para
   quieto	Apenas nos 1–3 lugares onde faz mais trabalho, nomeados	O início para cada traço distintivo (uma cor de destaque, uma face de exibição, uma textura, um motivo)
   completo	Em todo componente que se encaixa	O início apenas para o que toda página precisa: a superfície da página, a cor do texto e traços que não definem humor (como cantos quadrados)
   forte	Em todo componente que se encaixa, e com mais espaço: mais área, um uso de destaque	Apenas quando o usuário pedir mais

   Reduzir um traço quieto significa movê-lo para a coluna Deixar.

   Decida o estilo você mesmo (veja Decisões): escolha os traços, um nome cujo slug não esteja em uso (a menos que o usuário tenha pedido para revisar aquele estilo) e uma direção que não conflite com um estilo existente. Não pare aqui a menos que as referências conflitem de forma que nada resolva.

4. Escreva o guia. Cada execução tem sua própria pasta, para que nenhuma execução sobrescreva a outra:

   design/styles/
     index.md              cada estilo, onde se aplica, lista de assuntos compartilhada
     <slug>/
       style.md            o guia
       board.html          a verificação visual
       measured.json       o que measure.py leu das referências
       verify.md           quão próximo o painel corresponde a elas
       references/         capturas de tela das referências
   

   Copie assets/style.md deste skill para style.md e preencha-o. Mantenha cada título, em ordem, e escreva Nenhum para uma seção vazia, para que todos os guias sejam lidos da mesma forma. Escreva valores exatos (hex, px, nomes de fontes), para que outra sessão possa reconstruir o estilo sem as referências.

   • Evidência: uma linha por recorte medido, números copiados da saída de measure.py.
   • Tokens: cada token diz de onde veio: crop:<nome> (o valor é medido ali; uma cor deve corresponder à leitura daquele recorte ou a seu valor provavel), derived: <regra> (construído a partir de tokens medidos, como um tom de hover ou uma cor de texto escurecida para 4,5:1), ou chosen: <motivo> para o que nenhuma referência mostra, como estados e corpo de texto. Tamanhos vêm de medições também: o tamanho da fonte é a altura da caixa alta (a altura da tinta de um recorte tipográfico de maiúsculas) ÷ a proporção da altura da caixa alta da fonte. Toda regra nomeia uma fonte de assunto real e não usa nada da coluna Deixar. Prefixe cada token com --<slug>-, para que estilos possam compartilhar uma página sem conflitar.
   • Componentes: dê a cada tipo de componente uma tabela de propriedades (propriedade, depois token ou valor exato, para cada estado), para que possa ser reconstruído sem adivinhação. Use tokens onde quer que um exista. Siga a intensidade de cada traço: um componente fora dos lugares nomeados de um traço quieto usa os tokens mais simples do estilo, como a face de corpo ou a cor da tinta.
   • Mapeamento: mapeie cada token, classe ou variável existente do passo 2, e cada tipo de componente, para seu novo token ou especificação de componente. É disso que a aplicação do estilo parte, então não deixe nada no projeto sem mapear: escreva Manter ou Descartar com um motivo onde nada o substitui.

5. Mostre o estilo, depois itere. Leia references/board.md, copie assets/board.html como uma cópia de arquivo (não redigitando) e preencha seus placeholders apenas a partir do guia: todo tipo de componente com estados, uma seção Estilos, uma seção real muito pequena e movimento, cada um marcado com data-crop para o recorte de onde veio. Em seguida, verifique-o contra as referências e confira-o contra o guia, e corrija cada falha você mesmo, por no máximo três rodadas:

   python3 <este skill>/scripts/verify.py design/styles/<slug>
   python3 <este skill>/scripts/check.py design/styles/<slug>
   

   Abra o painel no navegador do usuário e forneça os caminhos para board.html e verify.md.

   Em seguida, adicione o estilo e quaisquer novos itens de assunto a design/styles/index.md, criando-o a partir de assets/index.md se necessário. design/styles/ é o único lugar no projeto que este skill altera.

   Pare para a revisão com o bloco de Decisões: algo a mudar? A precisão é mostrada por verify.md, junto com qualquer coisa ainda falhando após três rodadas, para que o usuário julgue apenas direção e intensidade. Para cada rodada de feedback, atualize o guia, reconstrua apenas as partes afetadas do painel, depois execute verify e check uma vez e corrija o que eles reportarem por no máximo três rodadas sem desfazer as alterações do usuário. Atualize o índice se o nome ou a lista de assuntos mudar, reabra o painel e pergunte novamente. Cada rodada termina medida, para que o estilo salvo seja sempre preciso, independentemente de quando o usuário parar. Para ajustar um traço para cima ou para baixo, mude sua Intensidade (escreva (feedback do usuário) depois dela) e os componentes que ela atinge; os valores permanecem medidos, então isso não precisa de data-accept. Se o usuário quiser um traço mais ousado que a própria referência (maior, mais pesado, mais saturado), isso muda um valor: trate como abaixo. Uma alteração que o usuário pede é intencional mesmo quando se afasta de uma referência: atribua ao token chosen: user feedback e marque sua amostra data-accept com o mesmo motivo, para que verify reporte como intencional em vez de falhar, e nunca a desfaça para fazer verify passar. Se o usuário rejeitar a direção em si em vez de detalhes, não remende tokens: volte ao passo 3, releia as referências, escolha uma nova direção, reconstrua e pare para a revisão novamente.

   A execução termina quando o usuário não tem nada a mudar ou passa para outra coisa. Não há etapa de aprovação. Para usar o estilo depois, o usuário o nomeia, e o skill o aplica (veja Aplicando um estilo salvo).

Aplicando um estilo salvo

Quando o usuário nomear um estilo salvo para usar, como "aplicar <slug> em tudo" ou "usar <slug> na página de preços", leia references/rollout.md e siga-o. Ele funciona apenas a partir do guia: adiciona os tokens do guia ao projeto, depois percorre o Mapeamento linha por linha, reformatando cada componente a partir de sua tabela de propriedades sem alterar seu conteúdo ou estrutura. Pule os passos 1–5: o estilo já está definido.

Exemplo

Leia examples/drafting-sheet/style.md e verify.md; os arquivos JSON e board.html são saída gerada, vale a pena abrir apenas para ver as tags data-crop. examples/drafting-sheet/ é uma execução concluída: uma referência de folha de desenho medida em oito recortes, o guia e um painel cujas 36 medições correspondem (uma intencionalmente).

Referências: desenhos técnicos e plantas, para um site sobre uma roda em crescimento.

• Adotar: linhas finas e precisas, grades regradas, etiquetas técnicas pequenas, anotação densa.
• Deixar: o bloco de título de cada desenho, partes e layout da folha.
• Assunto: uma roda em crescimento de 5,5 m, dimensões reais de estrutura, desenhos de engenharia.
• Regra: linhas de dimensão de planta + dimensões reais da estrutura = figuras anotadas com seus valores medidos.