macos-design-guidelines

Visão geral do skill macos-design-guidelines

macos-design-guidelines é um guia prático para desenhar e revisar apps para Mac com base nas Apple Human Interface Guidelines, com foco em decisões que impactam a qualidade real do produto final: barra de menus, controle por teclado, comportamento de janelas, toolbars, acessibilidade e integração com o sistema. Ele é mais indicado para equipes que constroem com SwiftUI, AppKit, Mac Catalyst ou estão portando uma experiência de iPad para o Mac.

Para que serve este skill macos-design-guidelines

Use este skill macos-design-guidelines quando você precisar de algo além de recomendações genéricas de UI e quiser regras específicas de Mac que mudam escolhas de implementação. Ele ajuda a identificar problemas como menus padrão ausentes, cobertura fraca de atalhos, persistência ruim de janelas ou controles que ignoram convenções de desktop.

Quem deve instalar

Instale se você é desenvolvedor, designer ou revisor trabalhando em um produto para macOS em que fluxos primeiro pelo teclado, comportamento multiwindow e descoberta de comandos por menus fazem diferença. Também é útil para agentes que precisam avaliar se um recurso de Mac está “pronto” de um jeito que corresponda às expectativas do usuário.

O que o torna diferente

O skill macos-design-guidelines é organizado em torno de regras acionáveis, e não de princípios amplos, então fica mais fácil aplicá-lo na implementação e na revisão de código. O maior valor está nas seções críticas: barra de menus, janelas, teclado e acessibilidade. São justamente essas áreas que mais bloqueiam adoção quando estão erradas.

Como usar o skill macos-design-guidelines

Instale e localize os arquivos-fonte

Execute o comando de instalação do macos-design-guidelines para este repositório e comece por SKILL.md e AGENTS.md. Para se orientar mais rápido, leia também metadata.json e rules/_sections.md antes de mergulhar no texto completo das regras.

Transforme uma solicitação vaga em um prompt útil

Um prompt fraco como “torne este app mais parecido com um app de Mac” é genérico demais. Um prompt melhor de uso do macos-design-guidelines diz o que você está construindo, qual framework usa e quais superfícies importam:

• “Revise este app de documentos em SwiftUI para macOS. Verifique cobertura da barra de menus, persistência de janelas e atalhos de teclado.”
• “Aplique macos-design-guidelines para Design Implementation a este fluxo de sidebar em AppKit. Identifique convenções de Mac ausentes.”
• “Avalie se esta tela em Mac Catalyst deve usar toolbar, menu de contexto ou comando na barra de menus.”

Leia o repositório na ordem certa

Na maioria das tarefas, o melhor caminho de leitura é SKILL.md primeiro, depois rules/_sections.md para o mapa de categorias e, por fim, as seções de regra relevantes em SKILL.md. Use AGENTS.md quando quiser as prioridades de decisão reunidas em um só lugar. Essa ordem ajuda a evitar leitura excessiva e mantém o foco nas regras com maior chance de afetar a implementação.

Dicas de fluxo de trabalho que melhoram a qualidade da saída

Use o guia macos-design-guidelines como checklist, não como texto para imitar. Informe logo de início o tipo de app, o público-alvo e o modelo de interação. Inclua qualquer restrição que importe, como “single-window utility”, “document-based app” ou “Catalyst port”, porque isso muda quais regras são mais importantes e evita recomendações genéricas.

FAQ do skill macos-design-guidelines

O macos-design-guidelines serve só para apps em SwiftUI?

Não. O skill macos-design-guidelines cobre SwiftUI e AppKit, e também é relevante para trabalhos em Mac Catalyst e Designed for iPad quando o produto precisa se comportar como um app real de Mac.

Quando não devo usar?

Não dependa dele para decisões de UI só de iOS, trabalho de identidade visual sem interação com desktop ou ideias de recurso que não afetam o comportamento no macOS. Se o seu app não foi pensado para seguir as convenções do Mac, este skill pode impor restrições desnecessárias.

Em que isso é diferente de um prompt normal?

Um prompt normal pode sugerir um comportamento “com cara de Mac”, mas o macos-design-guidelines oferece um conjunto estruturado de regras, com níveis de prioridade e expectativas específicas de implementação. Isso o torna melhor para revisão, QA e decisões de design em que deixar passar uma convenção de desktop pode gerar uma experiência ruim.

É amigável para iniciantes?

Sim, desde que você descreva o app com clareza. O skill é especialmente útil para iniciantes porque explicita os padrões do Mac que os usuários esperam, como barra de menus, atalhos e tratamento de janelas, em vez de deixar essas escolhas implícitas.

Como melhorar o skill macos-design-guidelines

Forneça o contexto do app que o skill não consegue inferir

A principal melhoria vem de informar se o app é baseado em documentos, focado em utilitários ou centrado em conteúdo, e se é feito em SwiftUI, AppKit ou Catalyst. Esses detalhes afetam a estrutura de comandos, o comportamento das janelas e o quanto de chrome do sistema o app deve expor.

Peça revisão baseada em regras, não só ideias

Para usar melhor o macos-design-guidelines, peça uma auditoria em áreas específicas: barra de menus, janelas, teclado, acessibilidade ou comportamento da toolbar. Por exemplo: “Revise este recurso contra o macos-design-guidelines e liste apenas as violações que realmente importariam para um usuário de Mac.”

Dê insumos concretos para que a primeira análise já seja útil

Inclua a UI atual, os comandos existentes e quaisquer atalhos ou comportamentos de janela já implementados. Se você quer ajuda com Design Implementation, cole a descrição da tela relevante ou um trecho de código, para que o skill identifique convenções de Mac ausentes em vez de adivinhar.

Itere primeiro sobre as lacunas de maior risco

Depois da primeira resposta, corrija as falhas críticas antes de polir os detalhes. Na prática, isso normalmente significa menus padrão, cobertura de atalhos, estado da janela e acessibilidade. Execute o skill novamente com o design ou código atualizado para que ele verifique se o guia macos-design-guidelines foi aplicado de forma consistente, e não só na superfície.