jovd83/prototipagem-esboçada

Skill de Prototipagem Esboçada

Faça uma aplicação web funcional parecer desenhada à mão, para que os clientes vejam que é um protótipo, não um produto final. Esta é apenas uma skin visual. É puramente aditiva e totalmente reversível.

Limites de escopo (leia primeiro, nunca viole)

1. Apenas toque nos pontos de entrada de estilo e no index.html. Adicione uma folha de estilo, cole um bloco SVG, defina dois atributos. Nada mais.
2. Nunca edite componentes, templates, lógica .ts/.tsx/.jsx/.vue, roteamento, estado, serviços ou testes.
3. Nunca substitua componentes por bibliotecas de componentes esboçados (ex.: wired-elements) — isso reescreve o markup. Proibido.
4. Nunca recolorir ou distorcer logotipos, fotos, gráficos ou ícones que precisam permanecer nítidos — use a classe de exclusão.
5. A reversão deve ser trivial: remover os dois atributos do <html> desativa toda a skin.

Como funciona (um modelo mental)

• Uma folha de estilo assets/sketch-skin.css define todos os 5 estilos + a rampa de esboço.
• Um bloco SVG assets/sketch-filters.html define os filtros de ondulação (#sketch-25 … #sketch-100).
• A ativação é feita com dois atributos no <html>: data-sketch="<estilo>" e data-sketch-level="<0|25|50|75|100>".
• A aparência vem de: troca de fonte manuscrita + caixas desenhadas à mão (border-radius irregular, preenchimentos planos) + um filtro de deslocamento SVG cuja intensidade é o nível de esboço. A fonte carrega o texto; o filtro ondula apenas a decoração das caixas (nunca desfoca o texto).

Início rápido (faça nesta ordem)

1. Confirme que o pedido é apenas visual. Se o usuário quiser alterações de comportamento/layout, pare — isso está fora do escopo.
2. Detecte o framework e encontre sua folha de estilo global + index.html (veja a tabela de receitas abaixo).
3. Escolha um estilo (tabela em "Estilos") e um nível (0, 25, 50, 75 ou 100).
4. Adicione o CSS da skin aos estilos globais do projeto:
   • Copie assets/sketch-skin.css para o projeto (ex.: src/styles.scss) ou faça @import. O @import da fonte já está dentro desse arquivo (uso online).
5. Cole os filtros SVG de assets/sketch-filters.html imediatamente após a abertura da tag <body> no index.html. (Obrigatório — filter: url(#sketch-…) só resolve se essas definições estiverem no DOM.)
6. Ative editando a tag <html> no index.html:

   <html lang="pt" data-sketch="balsamiq" data-sketch-level="50">
   

7. Verifique no navegador. Para reverter, exclua os dois atributos data-sketch* (o CSS/SVG adicionado pode permanecer dormente — eles não fazem nada sem os atributos).

Estilos

data-sketch	Aparência	Fonte	Uso
balsamiq	Wireframe limpo em escala de cinza, caixas planas	Balsamiq Sans	O padrão "isto é um mockup"
sharpie	Marcador preto em negrito, traço pesado	Permanent Marker	Esboço de quadro branco / workshop
pencil	Grafite leve, traços suaves	Gaegu	Rascunho suave "lápis no papel"
doodle	Divertido, acentos de cor clara	Short Stack	Conceitos informais e amigáveis
blueprint	Tinta branca em papel azul	Patrick Hand	Sensação técnica de "prancheta de desenho"

Nível de esboço

data-sketch-level controla o quanto as linhas tremem. Ele seleciona um filtro de deslocamento SVG diferente:

Nível	Efeito
0	Caixas desenhadas à mão + fonte, mas linhas retas e firmes (mais limpo)
25	Ondulação sutil
50	Claramente desenhado à mão (padrão recomendado)
75	Esboço solto e energético
100	Muito áspero, "rabisco" máximo

Se data-sketch estiver definido, mas data-sketch-level for omitido, a skin assume o nível 50 como padrão.

Marca d'água diagonal (opcional)

Para carimbar toda a tela como rascunho, adicione um terceiro atributo <html> com o texto a ser exibido:

<html data-sketch="balsamiq" data-sketch-level="50" data-sketch-watermark="RASCUNHO">

data-sketch-watermark pinta uma palavra fraca e manuscrita diagonalmente na viewport. É uma camada fixa e não interativa (pointer-events: none), portanto nunca bloqueia cliques, nunca altera o layout e permanece no lugar em mudanças de página e rota. Qualquer texto funciona (RASCUNHO, PROTÓTIPO, CONFIDENCIAL, um nome de cliente…). Remova o atributo para desativá-lo. Com a sobreposição, um campo de texto Marca d'água o define ao vivo.

Modais, popups e navegação SPA

Como a skin é ativada por atributos no <html> e estilizada com seletores globais [data-sketch] …, qualquer coisa que apareça após a ativação a herda automaticamente — diálogos, popovers, menus suspensos, dicas de ferramentas e toasts (incluindo os montados em portal), e cada tela para a qual você navega em um aplicativo de página única. Não há nada a conectar por componente ou por rota.

Duas coisas mantêm a consistência:

• As listas de seletores já cobrem dialog, [popover], [role="dialog"], [aria-modal="true"], .modal, .popover, menus, dicas de ferramentas e toasts, além do ::backdrop nativo.
• O script de sobreposição observa <body> e reinjeta os filtros SVG se um framework substituir o corpo em uma mudança de rota, para que a ondulação nunca desapareça silenciosamente. (Com o modelo de atributo estático, cole sketch-filters.html uma vez após <body>; frameworks SPA montam em uma raiz filha e a deixam intacta.)

Receitas de injeção por framework

A skin é independente de framework. Estes são os alvos exatos; detalhes completos em references/implementation.md.

Stack	Adicionar CSS a	Colar SVG em	Definir atributos em
Angular	src/styles.scss (ou styles.css)	src/index.html após <body>	<html> em src/index.html
React / Vite	src/index.css (importado em main.tsx)	index.html após <body>	<html> em index.html
Vue	src/assets/main.css (importado em main.ts)	index.html após <body>	<html> em index.html
HTML estático	link sketch-skin.css em <head>	index.html após <body>	<html> em index.html

Mantendo ativos específicos nítidos (exclusão)

A skin não editará o markup, mas se o usuário pedir explicitamente para proteger um elemento (logotipo, gráfico), a única alteração de markup permitida é adicionar o gancho de exclusão a esse único elemento:

<img src="logo.svg" class="no-sketch" alt="Logo">

.no-sketch (ou data-no-sketch) remove o filtro de ondulação e as substituições de cor desse elemento. Use com moderação e apenas quando solicitado.

Sobreposição de pré-visualização interativa (opcional)

Quando o usuário quiser alternar estilos ao vivo (ex.: mostrar a um cliente uma troca), use a sobreposição em vez de atributos estáticos:

1. Adicione assets/sketch-skin.css aos estilos globais (como no Início rápido).
2. Adicione uma tag de script antes de </body>:

   <script src="sketch-toggle.js" defer></script>
   

3. Pronto. O script renderiza um painel flutuante com OFF + um rádio por tema, um controle deslizante de esboço de 0–100%, e um campo de texto para marca d'água, altera os atributos <html> ao vivo e lembra a escolha em localStorage. Ele injeta automaticamente os filtros SVG (e os reinjeta se um SPA substituir o corpo), portanto, a etapa 5 do Início rápido (colar sketch-filters.html) não é necessária.

Isso ainda é apenas visual e não destrutivo — o script apenas define atributos. Remova a tag para desativar. Escolha este modelo quando o pedido for "deixe-me/o cliente alternar estilos"; use atributos estáticos para uma aparência fixa e estável para capturas de tela.

Galeria de capturas de tela

README.md mostra cada estilo e a escada de 0→100% usando os PNGs em demo/screenshots/. Essas imagens são pré-renderizadas; o aplicativo de demonstração interativo e o script de captura Playwright que as geram vivem na fonte de desenvolvimento do projeto e não são empacotados com a skill instalada. A skill em si é apenas assets/ + references/ — sem etapa de compilação, sem dependências.

Exemplos

Exemplo 1 — Demonstração Angular em Balsamiq, esboço moderado

• Entrada: "Faça este aplicativo Angular parecer um wireframe Balsamiq para a demonstração de amanhã."
• Ações: anexar sketch-skin.css a src/styles.scss; colar filtros em src/index.html; definir <html data-sketch="balsamiq" data-sketch-level="50">.
• Resultado: o aplicativo funciona de forma idêntica; é renderizado como um wireframe em escala de cinza.

Exemplo 2 — React, sharpie máximo

• Entrada: "Aplicativo React, aparência total de marcador de quadro branco, bem áspero."
• Ações: importar sketch-skin.css em main.tsx; colar filtros em index.html; definir data-sketch="sharpie" data-sketch-level="100".

Exemplo 3 — Desligar

• Entrada: "Volte para a UI real."
• Ação: excluir data-sketch e data-sketch-level do <html>. Pronto — nenhuma outra alteração necessária.

Solução de problemas

Sintoma	Causa	Correção
Caixas parecem desenhadas à mão, mas as linhas estão perfeitamente retas	Filtros SVG não estão no DOM, ou nível 0	Confirme que sketch-filters.html foi colado após <body>; defina nível ≥ 25
Nada mudou	Atributos ausentes ou CSS não carregado	Verifique se <html data-sketch="…"> está presente e sketch-skin.css está nos estilos globais
O texto parece desfocado	Filtro aplicado ao texto/corpo inteiro	Não adicione filter: ao body ou ao texto; a skin filtra apenas a decoração das caixas — recopie sketch-skin.css sem modificações
As fontes não são manuscritas	Offline / Google Fonts bloqueadas	Hospede as fontes localmente — veja assets/fonts/README.md
A página fica lenta em tabelas/grades enormes	Custo do feDisplacementMap em grande DOM	Diminua o nível ou escope a lista de seletores de ondulação (veja references/implementation.md)
Um logotipo ficou dessaturado/ondulado	Nenhuma exclusão nesse ativo	Adicione class="no-sketch" a esse único elemento
Fontes de ícone / ícones SVG desapareceram	Nivelamento agressivo	Adicione no-sketch ao contêiner do ícone, ou veja a nota de ícone em references/implementation.md

Arquivos de referência (leia apenas quando necessário)

• references/styles.md — especificação exata de fonte/paleta/traço para cada um dos 5 estilos e como adicionar um novo estilo.
• references/implementation.md — matemática do filtro SVG, passo a passo por framework, ajuste de seletor, fontes offline, desempenho, detalhes de reversão.