Skill de design responsivo no Claude Code: como escrever regras de breakpoint que o modelo realmente segue

Fala aí, beleza? A tela que o Claude Code entregou ficou linda no seu monitor de 27 polegadas

Aí você abre no celular e o negócio desmonta: coluna estourando pra fora da tela, scroll horizontal do nada, o menu que sumiu e não virou nada no lugar

O problema quase nunca é o CSS gerado, se liga nisso

O problema é a instrução: você pediu "deixa responsivo" e não disse em qual largura, nem qual bloco vem primeiro quando tudo colapsa pra uma coluna, nem o que o menu deve virar abaixo de 1024px

O modelo não adivinha isso, ele escolhe

E escolha sem régua é sorteio 🙂

Nesse post a gente monta uma skill de design responsivo: uma pasta com um SKILL.md que transforma "deixa responsivo" em regra que o modelo consegue seguir, passo a passo

O que você precisa antes de criar a skill

Pouca coisa, na verdade:

• Claude Code instalado e rodando
• um projeto com frontend (pode ser uma tela só, serve de cobaia)
• a decisão de ONDE a skill vai morar

E o que é uma skill, afinal? É uma pasta com um arquivo SKILL.md dentro

Só isso

O caminho muda o alcance dela:

• ~/.claude/skills/<nome>/SKILL.md é a skill pessoal, vale em todos os seus projetos
• .claude/skills/<nome>/SKILL.md é a skill do projeto, fica dentro do repositório e é versionada no git

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Repara que escolher a pasta já é uma decisão de time, não é detalhe de organização: no primeiro caso a régua é sua e ninguém mais herda, no segundo ela entra no pull request e todo mundo passa a gerar tela do mesmo jeito

Se você ainda está decidindo o que vira skill e o que fica no arquivo de contexto do projeto, vale ler antes sobre onde as regras de design devem morar

O exemplo aqui assume Tailwind CSS v4, porque os breakpoints já vêm nomeados e fica fácil de mostrar

Mas a mecânica vale pra qualquer stack: troca os nomes dos utilitários e mantém as larguras

Passo a passo: escrevendo a skill de design responsivo

1. Criar a pasta e o SKILL.md

mkdir -p ~/.claude/skills/design-responsivo

Ou, se a régua é do time:

mkdir -p .claude/skills/design-responsivo

Agora o arquivo, que começa com um frontmatter YAML entre marcadores --- e segue em markdown puro:

---
name: design-responsivo
description: Use ao criar ou alterar qualquer tela, componente visual ou layout do frontend. Define breakpoints, ordem de empilhamento, comportamento de menu e as larguras de checagem obrigatórias antes de dar a tarefa por concluída.
---

# Design responsivo

Regras obrigatórias para qualquer UI gerada neste projeto.

O frontmatter aceita ainda allowed-tools (pra restringir as ferramentas que a skill pode usar) e disable-model-invocation (pra desligar o acionamento automático)

Mas o campo que importa MUITO aqui é a description: é ela que o Claude usa pra decidir quando acionar a skill

E por que isso pesa tanto? Por causa da divulgação progressiva: no início da sessão só entram no contexto o name e a description de cada skill, o corpo do SKILL.md só é carregado quando a skill é considerada relevante

Ou seja: se a description não disser QUANDO usar, o corpo lindo que você escreveu nunca vai ser lido

O erro comum deste passo: escrever description descrevendo o conteúdo ("contém padrões de responsividade e boas práticas de CSS") em vez do gatilho ("use ao criar ou alterar telas e componentes")

2. Fixar a tabela de breakpoints no corpo da skill

## Breakpoints (padrão do Tailwind CSS v4)

- sm: 40rem (640px)
- md: 48rem (768px)
- lg: 64rem (1024px)
- xl: 80rem (1280px)
- 2xl: 96rem (1536px)

Não inventar breakpoint fora desta lista sem me perguntar antes.

## Larguras de checagem obrigatórias

Todo layout precisa funcionar em 375px, 768px, 1024px e 1440px.

Essas quatro larguras não saíram do chapéu: são as mesmas que a skill oficial frontend-design da Anthropic, lá no repositório público anthropics/skills, fixa como checagem responsiva

O erro comum deste passo: deixar a lista de breakpoints implícita achando que "ele já conhece o Tailwind"

Conhecer não é o mesmo que estar obrigado a usar só aqueles

3. Escrever a regra mobile-first com todas as letras

## Mobile-first (o Tailwind é assim, não invente)

- Utilitário SEM prefixo vale em todas as larguras, inclusive mobile
- Utilitário COM prefixo vale daquele breakpoint PRA CIMA e permanece nos maiores
- md:flex aplica de 768px em diante, não "só no tablet"
- O estilo do mobile é o estilo sem prefixo. Nunca use sm: para "estilo de tela pequena"

O erro comum deste passo: pedir "o estilo do mobile" e receber tudo em sm:

O sm: significa "a partir do breakpoint small", e não "em telas pequenas", então quem paga a conta é justamente o 375px, que fica sem estilo nenhum

4. Definir a ordem de empilhamento item por item

## Ordem ao colapsar para uma coluna (abaixo de md)

1. Cabeçalho com logo e botão do menu
2. Título e subtítulo da página
3. Ação primária (botão principal)
4. Conteúdo principal
5. Filtros e barra lateral
6. Rodapé

A sidebar NUNCA sobe acima do conteúdo principal no mobile.

"Empilhe de forma lógica" não é instrução, é torcida

Lógico pra quem? A ordem que o modelo acha lógica é a ordem do DOM, e a ordem do DOM foi escrita pro desktop

O erro comum deste passo: listar só o que vem primeiro e deixar o resto em aberto

Se você nomear dois blocos e esquecer os outros quatro, os outros quatro voltam pro sorteio

5. Definir o comportamento do menu por faixa de largura

## Menu

- A partir de 1024px: navegação horizontal completa, todos os itens visíveis
- Abaixo de 1024px: botão que abre um menu compacto em painel
- Estado inicial ao carregar a página: FECHADO, em qualquer largura
- Ao abrir o painel, a página por trás não rola
- Fechar ao clicar em um item de navegação

Repara que tem três decisões aí que ninguém costuma escrever: o que aparece acima, o que vira menu compacto abaixo, e qual é o estado padrão quando a página abre

A terceira é a que mais quebra tela na prática, porque um menu que nasce aberto no mobile come a dobra inteira

6. Escrever os guardrails inegociáveis

## Inegociável

- Nenhum scroll horizontal no mobile, em nenhuma largura testada
- Todo alvo de ponteiro (botão, link, ícone clicável) tem no mínimo
  24 x 24 pixels CSS (WCAG 2.2, SC 2.5.8, nível AA)

O mínimo de 24 por 24 pixels CSS é o critério de sucesso 2.5.8 Target Size (Minimum) da WCAG 2.2, no nível AA, e ele prevê cinco exceções

Então a regra na skill é: cumpra os 24 por 24, e se achar que o caso cai numa das exceções, avise em vez de decidir sozinho

O erro comum deste passo: escrever "boa usabilidade no toque"

Isso não é verificável, e o que não é verificável o modelo declara como feito 😛

7. Decidir onde entra @container e onde entra media query

## Container queries

- Componente que aparece em contextos de largura diferente (card em grid,
  card em sidebar): use @container de tamanho
- Estrutura da página inteira: use os breakpoints da lista acima
- NÃO use container style queries neste projeto

O porquê da última linha: as container queries de tamanho (@container) são Baseline widely available, com suporte em todos os navegadores principais lançados desde 2023, então dá pra usar sem medo

Já as container style queries para custom properties são bem mais novas, só alcançaram Baseline newly available recentemente, e seguem limitadas a custom properties

Se o seu público ainda tem navegador velho, essa linha te salva de um bug que só aparece na máquina do cliente

8. Fechar a skill com a checagem final

## Antes de dizer que terminou

Percorra as quatro larguras, uma por uma: 375, 768, 1024 e 1440.
Para cada uma, confirme:

- sem scroll horizontal
- ordem de empilhamento igual à definida acima
- menu no comportamento definido para a faixa
- nenhum alvo de toque menor que 24 x 24

Se alguma falhar, corrija antes de responder.

Sem essa seção, a skill vira uma lista de boas intenções lida no começo e esquecida no fim da tarefa

Com ela, o próprio modelo tem um checklist pra fechar

Bora ver na prática?

Regra vaga x regra que o modelo consegue seguir

O guia oficial de autoria de skills da Anthropic tem um princípio que resolve metade da discussão: casar o grau de liberdade da instrução com a fragilidade da tarefa

Onde só existe um caminho seguro, você escreve instrução específica e guardrail exato (ponte estreita)

Onde muitos caminhos funcionam, você dá direção geral e deixa o modelo trabalhar (campo aberto)

Breakpoint, ordem de empilhamento e menu são ponte estreita

Escolha de espaçamento e de paleta é campo aberto

O padrão das linhas é sempre o mesmo: troque o adjetivo por um número, uma ordem ou uma faixa

Adjetivo o modelo interpreta, número ele cumpre

Quando a skill é pessoal, quando é do projeto e quando vira plugin

Dev solo que quer a mesma régua em todo projeto. Skill pessoal em ~/.claude/skills/design-responsivo/SKILL.md e pronto: vale em qualquer pasta que você abrir, sem sujar repositório de cliente

É o cenário mais comum de quem toca vários projetos pequenos, e também de quem resolve bastante coisa sem escrever código e depende da régua estar sempre ligada

Time com design system próprio. Aí a skill precisa morar em .claude/skills/design-responsivo/SKILL.md, dentro do repositório

O motivo é simples: se os breakpoints do design system mudarem, a mudança entra no mesmo commit que muda o CSS, revisada no mesmo pull request

Régua de layout fora do git envelhece calada

Time que precisa espalhar a régua por vários repositórios. Nesse caso, marketplace de plugins

Você adiciona o marketplace e instala:

/plugin marketplace add owner/repo
/plugin install nome-do-plugin@nome-do-marketplace

O owner/repo também aceita URL git completa ou pasta local, o que ajuda em time com repositório privado

E se você quer um ponto de partida em vez de folha em branco, a Anthropic mantém uma skill oficial de design de frontend, a frontend-design, no repositório público anthropics/skills

É dela que saem as quatro larguras de checagem e a proibição de scroll horizontal no mobile que a gente usou aqui

Copiar e adaptar pro seu contexto é um caminho bem melhor do que escrever tudo do zero 🙂

Conclusão

A ideia central é essa: o modelo não adivinha a largura, não adivinha a ordem e não adivinha o menu

Cada uma dessas decisões que você deixa em aberto vira uma quebra no mobile depois, e você acha que é culpa do CSS gerado quando na verdade é a instrução que estava vaga

Próximo passo concreto pra hoje: cria o SKILL.md com a tabela de breakpoints e os dois guardrails (sem scroll horizontal, alvo de 24 por 24), roda numa tela real do seu projeto e vai apertando exatamente as regras que o modelo desobedeceu

Skill boa não nasce completa, ela nasce curta e engorda a cada tela que quebrou

E vale abrir a frontend-design lá no anthropics/skills pra comparar com a régua do seu time: sempre tem uma linha que você não tinha pensado em escrever…

até o próximo post! 😀