Gentle Design (Design gentil)

Contrato de Ativação

Use esta skill por padrão sempre que o usuário pedir, em palavras simples, por um design de UI, mockup, tela, landing page ou direções visuais, ou iterar em pranchetas sob design/. Não a use para implementar código de produção no stack do projeto.

Os comandos /gentle:design são atalhos opcionais: toda ação também funciona a partir de uma solicitação simples, por meio desta skill e da ferramenta gentle_design (list, open, stop, implement, handoff).

Regras Fixas

• Cada prancheta é um único arquivo HTML autocontido: CSS, JS e SVG inline; apenas pilhas de fontes do sistema. Nunca referencie URLs externas, CDNs, fontes remotas, imagens ou scripts.
• Use conteúdo realista para o público; sem lorem ipsum ou nomes de espaço reservado.
• Marcação acessível: elementos semânticos e landmarks, contraste WCAG AA, estilos de foco visíveis, prefers-reduced-motion respeitado para qualquer movimento.
• Quando design/system.md existir, leia-o primeiro e use apenas seus tokens e regras de componentes; execute a Auto-verificação de "Sincronização de design system" antes de finalizar qualquer prancheta.
• Faça no máximo uma pergunta esclarecedora, e apenas quando o brief não tiver o objetivo ou o conteúdo.
• Iteração edita apenas a prancheta alvo. Nunca reescreva as outras.

Portões de Decisão

Situação	Ação
Novo brief	Escreva N direções claramente diferentes (3 por padrão, ou o número solicitado) para um novo design/<slug>/
Feedback em uma prancheta	Edite apenas aquele arquivo; mantenha sua entrada no manifesto, atualize tradeoff se mudou
"Salvar e tentar uma abordagem diferente"	Adicione uma nova prancheta com o próximo NN; mantenha as anteriores; anexe-a ao manifesto
Usuário quer ajustar valores (espaçamento, cor, escala tipográfica)	Adicione controles deslizantes ou controles na prancheta mais um botão "Copiar como prompt" que copia os valores escolhidos como um prompt
design/<slug>/ já existe para um novo brief	Escolha um novo slug; nunca sobrescreva outro design
Uma mensagem traz comentários de design, ou o usuário pede para aplicá-los	Siga "Comentários do canvas" abaixo
/gentle:design sync, ou o usuário pede para capturar o design system do projeto	Siga "Sincronização de design system" abaixo
O usuário pede para mostrar, parar ou listar designs, ou para implementar uma prancheta	Chame a ferramenta gentle_design (open, stop, list, ou implement com <slug>/<artboard>); siga o texto de handoff que implement retorna, e reporte o progresso com action "handoff": status: "in_progress" quando começar, status: "implemented" quando terminar, com previewUrl definido para a URL de loopback do aplicativo em execução quando um estiver rodando

Antes de projetar

Execute este portão antes de cada novo brief: chame a ferramenta gentle_design com action: "list", então:

list reporta	Ação
system.exists false e designSources presente	Execute "Sincronização de design system" primeiro, informe ao usuário em uma linha que você sincronizou o design system do projeto, então projete com ele
Nenhum designSources	Pule a sincronização e projete livremente
system.staleSources presente	Nomeie essas fontes, diga que design/system.md pode estar desatualizado e ofereça sincronizar novamente antes de projetar; ressincronize apenas com a autorização do usuário e nunca use os tokens obsoletos silenciosamente

Etapas de Execução

1. Pegue o brief: objetivo, layout, conteúdo, público.
2. Carregue gentle-ui-design: leia seu SKILL.md e apenas as referências que correspondem ao público, tarefa principal e condição de sucesso do brief. Esta skill cuida da entrega; aquela cuida da qualidade de UX.
3. Escolha um slug em kebab-case a partir do brief.
4. Faça as direções diferirem em estrutura ou estratégia visual, não apenas na cor. Rotule cada uma com o trade-off que ela faz.
5. Escreva design/<slug>/NN-<nome>.html por prancheta (01-…, 02-…; nome em kebab-case).
6. Escreva design/<slug>/design.json:

{
  "title": "Página de preços",
  "brief": "Página de preços para um aplicativo de anotações voltado para estudantes",
  "feature": "odd/tasks/pricing-page.md",
  "artboards": [
    { "file": "01-comparison-table.html", "title": "Tabela comparativa", "tradeoff": "Denso e escaneável; apelo emocional mais fraco", "width": 1440, "height": 900 },
    { "file": "02-single-plan-hero.html", "title": "Herói de plano único", "tradeoff": "Foco forte; esconde diferenças de planos", "width": 1440, "height": 900 }
  ]
}

7. Defina width/height para a viewport pretendida da prancheta em pixels CSS; mantenha o manifesto sincronizado com os arquivos em cada alteração. Campos: title, brief, feature opcional e artboards[] com file, title, tradeoff, width, height.
8. Link ODD: quando o design vier de uma funcionalidade ODD rastreada (um odd/tasks/<feature>.md existente para o trabalho atual), defina feature para esse caminho e anexe uma entrada ao ## Log desse documento nomeando design/<slug>/ e suas pranchetas. Quando uma prancheta desse design for entregue para implementação, a entrada do Log também nomeia a prancheta escolhida (a entregue; list a reporta como Chosen) e que as outras são alternativas. Para trabalhos pequenos não rastreados, omita feature e deixe o design independente; nunca crie um documento de funcionalidade apenas para vinculá-lo.
9. Auto-verificação de UX, para cada prancheta que você finalizar: avalie-a contra as orientações de composição-e-feedback (hierarquia, densidade, feedback) e interfaces-adaptativas (telas estreitas, acesso a entrada, estados) de gentle-ui-design, e corrija cada lacuna antes de relatar.
10. Após escrever ou alterar pranchetas, chame a ferramenta gentle_design com action: "open" e o slug, a menos que o usuário tenha dito para não fazer. Quando uma aba do canvas já estiver aberta, ela atualiza essa aba em vez de abrir uma nova, então chame-a após cada alteração. Reporte a URL que ela retorna.

Sincronização de design system

1. Leia apenas, e nunca edite o código-fonte do projeto. Fontes: propriedades personalizadas CSS (:root, @theme, [data-theme]), a configuração do Tailwind ou v4 @theme, pastas de bibliotecas de componentes, arquivos de tokens existentes e as fontes que eles declaram.
2. Escreva design/system.md: cores (nome do token, valor, uso), tipografia, espaçamento, raio, sombras e regras de componentes. Cada entrada nomeia seu path de origem. Registre apenas valores encontrados nas fontes.
3. Escreva design/system.html: uma prancheta autocontida, com 1440 px de largura, que renderiza esses tokens (amostras, escala tipográfica, espaçamento, raio, sombras) e os componentes principais, sob as mesmas regras de nenhuma URL externa. O canvas a mostra como a primeira placa de cada design.
4. Quando não existirem fontes de design, diga isso e proponha um sistema inicial mínimo para o usuário aceitar; nunca apresente valores inventados como tokens do projeto.
5. Auto-verificação, para cada prancheta que você finalizar enquanto design/system.md existir: liste as cores e famílias de fontes que a prancheta usa, compare-as com os tokens do sistema e corrija cada desvio antes de relatar.

Comentários do canvas

Comentários do canvas são armazenados em design/<slug>/comments.json; a sessão também os recebe como mensagens que nomeiam cada id de comentário.

1. Leia os comentários abertos com a ferramenta gentle_design_comments (action: "list", slug e file opcionais). Sem a ferramenta, leia design/<slug>/comments.json e use as entradas cujo status é "open".
2. Aplique cada comentário editando apenas a prancheta em seu file; use selector e excerpt para encontrar o elemento. Quando um comentário tiver um screenshot, olhe-o primeiro: ele chega anexado à mensagem do comentário, ou abra design/<slug>/<screenshot> com a ferramenta de leitura. Ele mostra o que o usuário viu, muitas vezes um estado de animação ou transição transitória que a prancheta estática não mostra.
3. Marque cada comentário aplicado como resolvido com a ferramenta (action: "resolve", slug, ids). Sem a ferramenta, defina seu status para "resolved" e resolvedAt para a hora ISO atual, mantendo todas as outras entradas e campos como estão. Deixe comentários que você não aplicou abertos e diga o porquê.

O formato do arquivo, para agentes que têm apenas acesso a arquivos:

{
  "version": 1,
  "comments": [
    { "id": "k3x9p2ab", "file": "02-bold.html", "selector": "body > header > h1", "excerpt": "Ship faster", "comment": "Torne o título mais curto.", "createdAt": "2026-10-26T10:00:00.000Z", "status": "open", "sentAt": null, "resolvedAt": null },
    { "id": "m7q2w9cd", "file": "02-bold.html", "selector": "#cta", "excerpt": "Start", "comment": "O botão pula durante a transição de hover.", "screenshot": ".screenshots/m7q2w9cd.png", "createdAt": "2026-10-26T10:05:00.000Z", "status": "open", "sentAt": null, "resolvedAt": null }
  ]
}

screenshot é opcional: um caminho relativo à pasta de design, sob .screenshots/, presente apenas quando o usuário anexou uma imagem.

Nunca exclua ou reordene entradas e mantenha o arquivo como JSON válido: o canvas se recusa a sobrescrever um arquivo que não consegue analisar.

Contrato de Saída

Retorne: o slug, cada arquivo de prancheta com seu título e trade-off, quais arquivos foram alterados nesta rodada, os ids de comentários resolvidos nesta rodada e qualquer pergunta em aberto. Forneça a URL do canvas da etapa 10, ou mencione que /gentle:design open <slug> mostra o canvas quando você não o abriu. Para uma sincronização, retorne os caminhos das fontes lidas, as contagens de tokens por grupo e se o sistema é um starter proposto; após uma sincronização automática de "Antes de projetar", diga que foi executada e reporte-a da mesma forma.

Referências

• design/system.md no projeto, quando presente — os tokens de design a serem seguidos.
• Skill gentle-ui-design — orientação de qualidade de UX emparelhada com cada prancheta.