flcker/figma-ui-desktop

Normas de Desenvolvimento de UI Desktop com Figma (Versão Framelink MCP)

Resolve o problema de baixa fidelidade ao desenvolver UIs desktop a partir de designs Figma. A causa raiz: tratar os "dados do canvas" do Figma (coordenadas absolutas, cores inline, empilhamento de camadas de pixel) como "dados de implementação" e copiá-los diretamente, resultando em layouts quebrados, cores e fontes imprecisas e recursos faltantes.

Por que usar Framelink em vez do Figma MCP Server oficial para desktop? A ferramenta principal do MCP oficial, get_design_context, gera apenas código Web por padrão (React/Tailwind, com opção para Vue/HTML/iOS) e não suporta Qt Widget / QML / WinUI / Flutter, além de ser paga. O Framelink é focado em "fornecer apenas dados Figma independentes de framework, deixando a tradução para o modelo" — essa "desvantagem" torna-se uma vantagem no cenário de múltiplos frameworks desktop: o modelo, ao receber os dados do canvas, pode traduzí-los para qualquer framework alvo, sem ficar preso ao Web.

Esta skill é direcionada às duas ferramentas do Framelink figma-developer-mcp:

Ferramenta	Canal	Função
get_figma_data	Canal de precisão	Busca dados do canvas por fileKey + nodeId: informações de layout, conteúdo, visuais e componentes
download_figma_images	Canal visual	Exporta SVG/PNG/GIF para um diretório local com base no ID do nó

Se o alvo for front-end Web (React/Vue/HTML), use figma-ui-web em vez desta skill.

Princípios Fundamentais

1. Canais duplos em paralelo, proibido codificar com apenas um canal. O canal de precisão fornece valores exatos; o canal visual fornece layout geral e texto. Usar apenas um deles certamente resultará em distorção.
2. Use valores exatos, sem estimativas visuais. Cores, tamanhos de fonte, pesos de fonte, espaçamento, cantos arredondados, bordas e sombras devem ser sempre os valores exatos do design.
3. Peça o design primeiro, não escreva UI por conta própria.
4. Após a implementação, a validação deve ser um ciclo fechado: compare screenshots do programa em execução com o design → corrija defeitos automaticamente → faça revisão manual e itere.

Fluxo de Trabalho

Fase 1: Leitura Rápida (Entender Requisitos e Estrutura)

Quando o design for muito grande, faça uma leitura rápida primeiro para evitar sobrecarga de contexto ao buscar tudo de uma vez:

1. Use get_figma_data para buscar a estrutura de alto nível (controle a profundidade da travessia com o parâmetro depth, começando superficialmente) para entender quais páginas, seções e controles existem.
2. Use download_figma_images para exportar a imagem geral da interface, compreendendo layout e texto.

Fase 2: Leitura Detalhada (Obter Dados Precisos Antes da Implementação)

Para a seção ou controle específico a ser implementado, chame simultaneamente:

• get_figma_data (com nodeId, lendo coordenadas, valores de cor, tamanhos de fonte, espaçamento, cantos arredondados e bordas nó por nó)
• download_figma_images (exportar a imagem daquela seção para confirmar as posições relativas dos controles)

Após obter os dados, faça uma análise estrutural antes de codificar:

• Quais nós são padrões repetidos (itens de lista, cards, botões) → Extraia para componentes/controles personalizados do framework alvo
• Quais posicionamentos absolutos são na verdade layouts (disposição horizontal, centralizada, alinhada às extremidades, grade) → Converta usando a tabela de mapeamento abaixo para o layout do framework correspondente
• Quais são papéis semânticos (navegação, formulários, listas) → Mapeie para a biblioteca de controles existente do framework alvo
• Nós de imagem/ícone → Baixe o arquivo original usando download_figma_images para o diretório de recursos; não desenhe manualmente

Fase 3: Implementação (Tradução Independente de Framework)

Use os valores exatos do design para cores, tamanhos de fonte e espaçamento. Ao traduzir, consulte a tabela de mapeamento "Conceito do Canvas → Framework Alvo" abaixo. Não invente controles — se o framework alvo possui layouts/controles padrão, use-os. Coordenadas absolutas só devem ser mantidas quando "realmente for necessário posicionamento preciso em pixels".

Fase 4: Ciclo de Validação

Ambientes desktop não possuem automação de navegador como Playwright. A validação deve ser: compile e execute o programa, tire screenshots e compare lado a lado com os screenshots do design. Corrija defeitos óbvios automaticamente; a revisão manual identifica problemas mais sutis (espaçamento, peso da fonte, pequenas diferenças de cor) — exponha-os ativamente ao AI para reparos precisos e entre na próxima iteração.

Tabela de Mapeamento: Conceito do Canvas → Framework Alvo

O canvas do Figma usa coordenadas absolutas + camadas de pixel. A implementação deve traduzir isso para os conceitos de layout de cada framework. Consulte esta tabela durante a tradução:

Conceito do Canvas/Design	Qt Widget	QML (Qt Quick)	WinUI 3 (XAML)	Flutter
Disposição horizontal	QHBoxLayout	Row	StackPanel (Orientation=Horizontal)	Row
Disposição vertical	QVBoxLayout	Column	StackPanel (Orientation=Vertical)	Column
Layout em grade	QGridLayout	Grid / GridLayout	Grid	GridView / Table
Posicionamento absoluto	setGeometry / move	Item + x/y	Canvas + Canvas.Left/Top	Stack + Positioned
Empilhamento/sobreposição	Sobreposição de widgets filhos / raise()	Propriedade z / Stack	Canvas.ZIndex	Stack
Centralização	addStretch / setAlignment	anchors.centerIn	HorizontalAlignment/VerticalAlignment=Center	Center / Align
Alinhamento às extremidades	addStretch em ambos os lados	anchors.left/right + margens	Distribuição de margens	MainAxisAlignment.spaceBetween
Espaçamento	QSpacerItem / spacing do layout	Propriedade spacing	Margin / Padding	SizedBox / Padding / Spacer
Cor	QPalette / stylesheet	Theme / bindings de propriedades	Dicionário de recursos ResourceDictionary	ThemeData / ColorScheme
Tamanho/fonte da letra	QFont	font.pixelSize	FontSize	TextStyle.fontSize
Cantos arredondados	stylesheet border-radius	Rectangle radius	CornerRadius	BorderRadius
Sombra	QGraphicsDropShadowEffect	DropShadow	ThemeShadow / DropShadow	BoxShadow
Ícone	QIcon / recursos	Image / fonte de ícones	FontIcon / SymbolIcon	Icon
Reutilização de componentes	Subclasse customizada de QWidget	Component QML customizado	UserControl / controle customizado	Widget
Estado/variações	Enum + update()	State / dirigido por propriedades	VisualStateManager	setState / AnimatedWidget

Regras de Ferro Contra Preguiça

A IA tende a usar apenas um canal para codificar. Exigir explicitamente:

• "Chame get_figma_data e download_figma_images simultaneamente para ler o design"
• "Não é permitido usar apenas imagens/screenshots do design para escrever código"
• "Leia linha por linha os valores exatos de get_figma_data, comparando cores, tamanhos de fonte e espaçamento; não faça estimativas visuais"
• "Traduza para os layouts/controles padrão do framework alvo de acordo com a tabela de mapeamento; não invente"

Lista de Verificação de Fidelidade

Após a geração, verifique item por item (mais confiável do que "parece no geral"):

• Cores (foram usados valores exatos, não aproximados)
• Tamanho/peso da fonte
• Espaçamento / margens / preenchimento
• Cantos arredondados / bordas / sombras
• Layout (foi traduzido para layouts padrão do framework alvo, não copiando coordenadas absolutas)
• Hierarquia / ordem de empilhamento
• Ícones/imagens usando arquivos originais, não desenhados manualmente
• Padrões repetidos foram extraídos para componentes/controles personalizados

Fontes de Referência

A metodologia é inspirada no fluxo oficial de desenvolvimento UI com Figma MCP + Playwright (veja "Usando Figma MCP e Playwright MCP para Melhorar a Eficiência no Desenvolvimento e Depuração de UI"). As ideias centrais de "canais duplos + ciclo de validação + exigências explícitas contra preguiça" são mantidas, com as ferramentas adaptadas para o Framelink figma-developer-mcp e a tabela de mapeamento expandida para cobrir múltiplos frameworks desktop.