Communitygithub.com

turtleneck

Skill de design para UI web e de apps que detecta o que está sendo construído e aplica um preset estilístico — como keynote, enterprise, cinema, vibe, power, devtool, lab, journey, market, vault, drive — cada um uma combinação de cinco grandes sites de referência por categoria, com receitas para HTML/CSS puro, Tailwind (v3/v4, shadcn) e SwiftUI.

O que é turtleneck?

O turtleneck é um skill especializado em design para interfaces web e de aplicativos, que oferece uma abordagem disciplinada e consistente para estilização. Ele funciona detectando automaticamente o tipo de projeto (página de destino, painel administrativo, documentação, loja virtual, etc.) e seu setor (tecnologia, finanças, viagens, entretenimento) a partir de pistas como nome do projeto, arquivos de dependência, rotas e CSS existente. Com base nessa detecção, o skill seleciona um preset de estilo apropriado, como 'keynote' para uma aparência premium e clean, 'enterprise' para software empresarial, ou 'cinema' para streaming de vídeo. Cada preset é uma mistura de cinco grandes sites de referência de sua categoria, e nunca uma cópia de um deles. O skill fornece um sistema de tokens CSS reutilizáveis, receitas para construção de páginas (HTML, Tailwind e SwiftUI) e um workflow rigoroso que inclui verificação de responsividade, acessibilidade de cores e otimização para diferentes larguras de tela. É ideal para desenvolvedores que precisam criar ou reformular interfaces com rapidez e consistência, seguindo padrões visuais reconhecíveis e de alta qualidade.

Funciona com✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/n-stau/turtleneck/tree/main/skills/turtleneck

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que turtleneck faz?

Escolha o visual certo para o app e construa-o com disciplina. Cada visual é um preset: um arquivo de substituições de variáveis sobre um núcleo compartilhado. O preset padrão, keynote, é o próprio núcleo. Cada outro preset é uma combinação de cinco grandes sites de uma categoria, nunca uma cópia de um deles.

Quando este skill está ativo, ele substitui skills genéricos de "evitar padrões de IA" (como frontend-design) quando eles discordam: no keynote a fonte do sistema, sobrancelhas em caixa de frase e títulos com gradiente tonal estão corretos.

Arquivos próximos a este:

  • tokens.css: o núcleo e os valores do keynote. Cada cor é light-dark(light, dark); color-scheme em :root, .a-dark, .a-light ou data-theme escolhe a metade. Todos os hooks dos presets estão listados em seu :root. Componentes compartilhados também vivem lá: escala tipográfica, botões, tiles, .a-grid, .a-rail, .a-stats, .a-reveal.
  • styles/<preset>.css: substituições de variáveis mais algumas regras exclusivas do preset. Carrega após tokens.css.
  • styles/<preset>.md: uma página por preset: quando usar, tabela de tokens, regras, deltas de componentes, fontes, evitar, checklist.
  • recipes-html.md: esqueleto da página, navegação, hero, tiles, bento, galeria, comparar, rodapé (accordion em telefones), revelar, e os padrões de presets compartilhados (bandas invertidas, hero de busca, rails, tabela de especificações, cartões de planos, moldura de código).
  • tailwind.md, swiftui.md: os mesmos tokens para essas stacks.
  • test-widths.html?src=<url>[&h=800][&full=1]: a página em 320/375/414 lado a lado com um relatório de overflow; full=1 aumenta cada frame para a altura do documento para capturas de tela de página inteira em telefones.
  • example.html e ../../demos/ no repositório agent-skills: páginas finalizadas.

Passo 0: Detecte o tipo de app (obrigatório, antes de qualquer código)

  1. Um sistema de design existente ou um pedido de estilo explícito vence. Tokens do projeto, tema de uma biblioteca de componentes, um guia de marca, ou "faça escuro e vermelho": use isso, mantenha apenas as regras principais abaixo, pule a tabela.
  2. Leia os sinais: a solicitação; README; dependências (package.json, pyproject.toml, Podfile, Package.swift, Gemfile, *.csproj); rotas; CSS existente; a categoria do produto e o público.
  3. Escolha UM preset:
CategoriaSinais (solicitação, produto, deps, rotas)Preset
Hardware premiumProduto físico, dispositivo de consumo, gadget de estilo de vida, página de lançamento, "clean", "minimal", "premium"; telas de marketing SwiftUI; nenhum sinal clarokeynote
Software empresarialOffice/produtividade, B2B, CRM/ERP, intranet, TI/conformidade, saúde; deps @fluentui/*, @microsoft/teams-js, office-addin-*, @azure/*, Blazor/.NET; rotas /admin, /settings, /reportsenterprise
StreamingVídeo, filmes/TV, séries, trailers, eventos ao vivo, VOD; deps hls.js, video.js, shaka-player, @mux/*, react-player; rotas /watch, /browse, /titlecinema
Música e socialMúsica/áudio, playlists, criadores, feed social, namoro, aulas de fitness, assinatura jovem; deps howler, tone, wavesurfer.js, expo-av; rotas /player, /playlist, /profilevibe
Hardware gamerGPU/peças de PC, consoles, periféricos, esports, benchmarks, drivers, "FPS"; deps three, @react-three/fiber + libs de gráfico; rotas /specs, /compare, /driverspower
Desenvolvedor e cloudAPI, SDK, CLI, hospedagem, deploy, banco de dados, observabilidade, API de pagamentos, "para desenvolvedores"; deps next, @radix-ui/*, stripe, prisma, drizzle, trpc, turbo; rotas /docs, /changelog, /pricingdevtool
IAModelo, assistente, chat, agentes, "com tecnologia de IA" como o produto; deps openai, @anthropic-ai/sdk, ai, langchain, transformers; rotas /chat, /research, /modelslab
ViagensEstadas, voos, corridas, hotéis, reservas, itinerários; seletores de data, mapas (leaflet, mapbox-gl); rotas /search, /stays, /trips, /bookjourney
VarejoLoja, catálogo, marketplace, carrinho, checkout, ofertas, supermercado, moda; deps @shopify/*, @medusajs/*, @commercetools/*, snipcart, @stripe/stripe-js com um catálogo de produtos; rotas /shop, /products, /p/, /cart, /checkout, /categorymarket
FinançasBanco, cartão de crédito, pagamentos, carteira, seguro, empréstimos, investimentos, painel de contas para consumidores; deps plaid, react-plaid-link, @adyen/*, dinero.js, currency.js; rotas /accounts, /cards, /rates, /apply, /transfer (uma API de pagamentos vendida para desenvolvedores é devtool)vault
AutomotivoCarros, motocicletas, e-bikes, carregamento de VE, mobilidade, concessionárias, test drives; configuradores, páginas de alcance e especificações; rotas /models, /configure, /inventory, /test-drive, /dealersdrive
Tipo de páginaPreset (desempate)
Site de documentação, changelogdevtool
Painel administrativoenterprise para usuários empresariais; devtool para voltado a desenvolvedores
Lojamarket; uma página de produto premium única é keynote
Portfóliokeynote para trabalho de produto/design; cinema para filme, foto, motion
Tela de app mobilekeynote para utilitários com aparência nativa; vibe para mídia de consumo e social
Jogo / estúdio de jogospower para competitivo e relacionado a hardware; cinema para jogos narrativos, trailers
Funcionalidade de IA dentro de outro produtoa própria categoria do produto; lab apenas quando a IA é o produto
Fluxo de reserva dentro de outro produtojourney apenas para as páginas de busca e resultados

Palavras de estilo do usuário mapeiam diretamente: "Apple-like / premium / clean" = keynote; "Microsoft / Fluent" = enterprise; "Netflix-style" = cinema; "Spotify-like / TikTok-like" = vibe; "gaming / NVIDIA-like" = power; "Stripe / Vercel / GitHub style" = devtool; "OpenAI / Anthropic-like" = lab; "Airbnb / Booking-like" = journey; "Amazon / IKEA-like" = market; "banking / PayPal-like" = vault; "Tesla / BMW-like" = drive. O resultado é a combinação da categoria, nunca o site daquela empresa (veja "Marcas registradas e ativos").

  1. Sinais fracos ou conflitantes: keynote.
  2. Diga a escolha em uma linha antes de construir, por exemplo, "Estilo: devtool (Next.js + Prisma, rotas /docs e /pricing, vendido para desenvolvedores)." Em seguida, leia styles/<preset>.md completamente (keynote: styles/keynote.md).

O que um preset pode mudar

Apenas através das variáveis em tokens.css (:root) mais algumas regras próprias:

  • fontes (display, corpo, mono) e a escala tipográfica, pesos, tracking, altura de linha;
  • estilo de sobrancelha e introdução, tamanho do corpo (nunca abaixo de 14px para UI, 16px para texto de leitura);
  • cores de superfície e texto, claro/escuro padrão, o único acento e o texto sobre ele, cor de link e foco;
  • raios, bordas, sombras, preenchimento de tile; altura do botão, padding, peso, caixa;
  • altura da navegação, preenchimento e desfoque; larguras de conteúdo, espaçamento de seção e tile;
  • easing, durações, distância de revelação, feedback de hover e pressionamento;
  • sabor de imagem e cópia (em seu arquivo md).

Tudo abaixo desta linha vale para cada preset.

Fluxo de trabalho

  1. Respeite o projeto. Carregue tokens.css + styles/<preset>.css, ou mescle o tema Tailwind, ou adicione a paleta SwiftUI. Um preset pode linkar as fontes gratuitas que seu arquivo md nomeia; a página ainda deve parecer correta com a pilha de fallback. Nunca adicione uma dependência npm para estilização.
  2. Escreva o plano da página em 3 linhas: a única coisa que a página vende, a ordem das seções com fundos, e o único "momento" (um capítulo invertido, um bento de grande estatística, um demo, um vídeo, scroll fixo).
  3. Escreva o texto primeiro: headline curto (o preset define o comprimento), uma linha de subhead, introdução no máximo duas linhas.
  4. Construa a partir das receitas, seção por seção.
  5. Verifique em cada largura de teste (Responsivo), claro e escuro onde o preset tem ambos: captura de tela, verificação de overflow, checklist. Corrija antes de relatar como concluído.

Regras principais

Tipografia

  • Uma família para UI (mais mono apenas para código real, teclas e valores de API). O peso display vem do preset.
  • Tracking aperta conforme o tamanho aumenta; corpo nunca tem tracking negativo além de -0.022em.
  • Tamanhos display são fluidos clamp(min, rem + vw, max); sempre misture rem no termo do meio.
  • Corpo 16-17px para leitura; 14px apenas em UI densa, linhas de metadados e rodapés. Altura de linha 1.45-1.6 para corpo.
  • text-wrap: balance em headlines; palavras longas quebram (overflow-wrap, hyphens).
  • Números importantes são grandes e usam numerais tabulares; seus rótulos são pequenos.

Cor

  • Cores da marca primeiro. Uma cor da marca do usuário ou do projeto substitui o acento do preset, que é apenas o fallback. O preset ainda decide layout, tipografia, raios, densidade, imagens e movimento.
  • Receita de acento (cor da marca ou qualquer mudança de acento), definida uma vez em :root:
    • --a-blue: o preenchimento, ou seja, a cor da marca como fornecida (nome antigo mantido; significa "acento").
    • --a-on-accent: tinta ou branco, o que alcançar 4.5:1 no preenchimento.
    • --a-blue-hover: um tom mais escuro (mais claro em um padrão escuro) cujo rótulo ainda passe.
    • --a-accent-text: light-dark(a, b), o matiz da marca deslocado em luminosidade até alcançar 4.5:1 em --a-bg e --a-bg-alt em cada tema. Links, sobrancelhas de acento e o anel de foco (>= 3:1) o leem. Presets com um botão primário de tinta (lab, journey) mantêm a tinta em --a-button-*; a marca ainda vai aqui.
  • Um acento, escopo pequeno: CTA primário, foco, links, uma marca do logotipo, pequenos badges e marcadores "recomendado". Não superfícies grandes ou texto corporal, a menos que o preset diga o contrário. Cores de status apenas para status.
  • Superfícies neutras em 2 a 4 passos; separação por tom, linha fina ou um nível de sombra suave, conforme o preset diz.
  • O texto nunca é preto puro sobre branco; o cinza do corpo é um cinza real com contraste AA.
  • AA em todos os lugares: 4.5:1 para texto e para rótulos de botões em seu preenchimento, 3:1 para texto grande, ícones e bordas que carregam significado.
  • O modo escuro é uma paleta diferente, não invertida: um tom mais claro para superfícies elevadas, sem sombras para profundidade.

Layout e ritmo

  • O conteúdo tem limites: uma coluna de texto (--a-content) dentro de uma grade larga (--a-content-wide), calhas fluidas.
  • Seções alternam cor de página e cor alternativa; os tiles assumem o preenchimento oposto ao de sua seção.
  • Heroes centrais e aberturas de seção quando o preset diz assim; texto dentro de tiles e texto longo é alinhado à esquerda.
  • Um momento por página; no máximo um capítulo invertido (escuro ou claro), a menos que o preset seja construído em bandas.

Responsivo (regra rígida: toda resolução, todo preset)

  • Tipografia e espaçamento fluidos a partir dos tokens clamp; valor pequeno em 375px, grande em 1440px.
  • Sem larguras ou alturas fixas que possam quebrar: max-width + calha, min(), minmax(0, 1fr), aspect-ratio, min-height. Nunca 100vh (use svh/dvh). Filhos de flex/grid que contêm texto recebem min-width: 0.
  • Grades refluem por espaço: repeat(auto-fit, minmax(min(100%, 20rem), 1fr)), não breakpoints de dispositivo.
  • Escala de mídia: max-width: 100%; height: auto; SVGs mantêm um viewBox.
  • Navegação: abaixo de 834px (ou assim que 6+ links pararem de caber: consulta de contêiner) os links de texto se movem para um menu de tela cheia (popover nativo, sem JS); esconda seu <li> com uma regra que supera os estilos de link base (receitas: Navegação global). Mantenha a marca, busca e uma ação visíveis. Sem links de texto (apenas busca, conta, carrinho): sem hambúrguer.
  • Sem barra de rolagem horizontal em qualquer largura; apenas rolagens intencionais (galerias, trilhos, código) transbordam, dentro de sua própria caixa.
  • Alvos de toque >= 44x44px: pills pequenas, amostras, pás, links de navegação recebem uma área invisível de toque (.a-hit).
  • Áreas seguras: viewport-fit=cover; calhas e padding inferior usam env(safe-area-inset-*).
  • Telas muito grandes: tipo e conteúdo param em seus limites; fundos permanecem sangrados.
  • Paisagem do telefone: o hero não deve precisar da altura da viewport; nada fixo cobre mais de um terço.
  • Zoom 200%: equivale a uma viewport com metade da largura; tudo reflui, nada cortado.

Larguras de teste antes de dizer concluído (painel do navegador: resize_window para cada, captura de tela, mais document.documentElement.scrollWidth === innerWidth e uma lista de elementos mais largos que a viewport):

LarguraRepresenta
320telefones pequenos, zoom 200% de 640
375 / 414telefone padrão / grande
768 / 1024tablet retrato / paisagem, laptop pequeno
1280 / 1440laptop / desktop (largura de referência)
1920 / 2560full HD / QHD, ultrawide
812x375telefone paisagem
6401280px com zoom 200%

Relate por largura: captura de tela feita, overflow sim/não, o que foi corrigido. Headless Chrome prende janelas abaixo de 500px; teste larguras de telefone no painel do navegador ou com test-widths.html?src=<url da página> (mesma raiz http). Capturas headless: force o tema com data-theme="light|dark" em <html>; conteúdo de revelação é invisível em capturas estáticas, então passe --virtual-time-budget=5000 ou defina data-reveal="off" em <html>; um hero 100svh estica em uma janela de página inteira alta, então fixe-o (min-height: 800px) para a captura (&full=1 faz ambos).

Componentes

  • Botões: altura mínima 44px (visuais menores recebem a área de toque), caixa de frase a menos que o preset diga maiúsculas, sem ícones exceto um chevron ou seta à direita, sem gradientes. Primário preenchido, secundário conforme o preset.
  • Links: visivelmente links (cor ou sublinhado); chevrons estilo "Saiba mais ›" onde o preset os usa.
  • Tiles/cartões: uma parada de tab quando o tile inteiro linka (botão interno é um span). Raio, preenchimento, borda e sombra do preset; nunca todos de preenchimento + borda + sombra ao mesmo tempo.
  • Anel de foco: 2px sólido --a-focus, deslocamento 1px, em cada elemento interativo.
  • Navegação: sólida ou vidro conforme o preset, no máximo uma barra fixa, página atual marcada.
  • Rodapé: quieto: links pequenos cinzas em colunas, linha legal; colunas se tornam acordeões <details> em telefones.

Imagens

  • Assunto real: o produto, sua UI, as próprias fotos e mídia do usuário. Grandes, cortadas com intenção.
  • Nenhuma pessoa de banco de imagens em laptops, sem blobs 3D, sem emoji, sem mascotes, sem ícone na frente de cada título.
  • Sem ativos: desenhe o assunto uma vez como um <symbol> SVG recolorido por variáveis CSS, ou um placeholder cinza honesto na proporção correta.

Movimento

  • Transições nomeadas pr...

[truncado para tradução]

Habilidades Relacionadas