@promptui-lib/figma-parser

v0.1.18

Published

11 days ago

Figma API client and parser for PromptUI

0High
0Medium
0Low

desreemenezes

Índice

O que é o PromptUI?

PromptUI é uma biblioteca que converte automaticamente designs do Figma em código limpo e pronto para produção. Ela lê a API do Figma, parseia a estrutura do design e gera código específico para cada framework.

Principais Funcionalidades

Output Determinístico: Mesmo design = mesmo código, sempre
Múltiplos Frameworks: React, Material UI, Tailwind, Bootstrap, Flutter, SwiftUI
Design Tokens: Extrai automaticamente cores, espaçamentos, tipografia
HTML5 Semântico: Gera tags apropriadas (<button>, <nav>, <header>, <form>)
Auto Layout → Flexbox: Converte Auto Layout do Figma para CSS Flexbox
Posicionamento Absoluto: Suporta elementos sem Auto Layout
Google Fonts: Importa automaticamente as fontes detectadas
Composição de Componentes: Componentes # aninhados são importados automaticamente

Início Rápido

# 1. Instale globalmente
npm install -g @promptui-lib/cli

# 2. Configure seu projeto
npx @promptui-lib/cli init

# 3. Configure as credenciais do Figma
export FIGMA_TOKEN=seu_token_aqui
export FIGMA_FILE_ID=id_do_arquivo

# 4. Gere todos os componentes
npx @promptui-lib/cli generate

Instalação

npm install -g @promptui-lib/cli

Ou use com npx:

npx @promptui-lib/cli generate

Frameworks Suportados

| Framework | Comando | Output | | ---------------- | -------------------- | ---------------------------- | | React + SCSS | generate | TSX + BEM SCSS | | Material UI | generate mui | TSX + componentes MUI | | Tailwind CSS | generate tailwind | TSX + classes Tailwind | | Bootstrap | generate bootstrap | TSX + classes Bootstrap | | Ant Design | generate antd | TSX + componentes Ant Design | | Flutter | generate flutter | Dart StatelessWidget | | SwiftUI | generate swiftui | Swift View |

Comandos CLI

Gerar Componentes

# Exporta frames marcados com #
npx @promptui-lib/cli generate

# Exporta TODOS os frames de nível superior
npx @promptui-lib/cli generate --all

# Exporta node específico por ID
npx @promptui-lib/cli generate 3:100

# Preview sem salvar arquivos
npx @promptui-lib/cli generate --preview

# Com framework específico
npx @promptui-lib/cli generate tailwind
npx @promptui-lib/cli generate mui
npx @promptui-lib/cli generate bootstrap

Opções

| Opção | Descrição | | --------------- | ----------------------------------------- | | --all, -a | Exporta todos os frames de nível superior | | --force, -f | Sobrescreve arquivos existentes | | --output, -o | Diretório de saída customizado | | --preview, -p | Preview sem salvar | | --layer, -l | Força camada (atoms/molecules/organisms) | | --no-meta | Não gera meta.json |

Outros Comandos

# Inicializa configuração
npx @promptui-lib/cli init

# Sincroniza design tokens
npx @promptui-lib/cli sync tokens

# Inicia agente MCP
npx @promptui-lib/cli agent

Configuração

Crie promptui.config.json:

{
  "figma": {
    "token": "figd_...",
    "fileId": "ABC123xyz"
  },
  "output": {
    "basePath": "src/components",
    "styleFormat": "scss"
  }
}

Ou use variáveis de ambiente:

export FIGMA_TOKEN=figd_...
export FIGMA_FILE_ID=ABC123xyz

Obtendo Credenciais do Figma

Token:

Acesse Configurações do Figma
"Personal Access Tokens" → Criar novo

File ID: Da URL do Figma: https://www.figma.com/file/ABC123xyz/MeuProjeto → ABC123xyz

Entendendo o fileId vs node-id

⚠️ Importante: O fileId é do arquivo Figma inteiro, não de uma tela específica!

Na URL do Figma:

https://www.figma.com/design/5gCjy5F30XJySmOPpgDKLM/Tela-de-Login?node-id=13-2&m=dev
                              └──────────────────────┘              └──────┘
                                     fileId                         node-id (NÃO usar)

| Conceito | O que é | Precisa na config? | |----------|---------|-------------------| | fileId | Identifica o arquivo Figma inteiro | ✅ Sim | | node-id | Identifica um frame específico | ❌ Não |

Regra:

Mesmo arquivo Figma, telas diferentes → Use o mesmo fileId
Arquivo Figma diferente → Precisa de um novo fileId

Exemplo:

📁 Meu Projeto (fileId: ABC123xyz)
  ├── #LoginScreen     ← mesmo fileId
  ├── #HomeScreen      ← mesmo fileId
  ├── #ProfileScreen   ← mesmo fileId
  └── #SettingsScreen  ← mesmo fileId

O CLI busca automaticamente todos os frames que começam com # dentro do arquivo.

Guia para Designers

Regra Principal: Prefixo `#`

Para que um componente seja exportado, o nome do frame deve começar com #:

✅ #Button        → Será exportado
✅ #Card          → Será exportado
✅ #LoginScreen   → Será exportado
❌ Button         → Ignorado
❌ card-design    → Ignorado

Composição de Componentes

Componentes # aninhados são automaticamente importados:

#LoginScreen (organismo)
├── #Header (organismo)  → import { Header } from '../organisms/Header'
├── #Form (molécula)     → import { Form } from '../molecules/Form'
│   ├── field-email      → <input type="email" placeholder="Email">
│   ├── field-password   → <input type="password" placeholder="Password">
│   └── #Button          → import { Button } from '../atoms/Button'
└── #Footer (organismo)  → import { Footer } from '../organisms/Footer'

Auto Layout é Essencial

Sempre use Auto Layout nos seus frames. O PromptUI converte:

| Figma Auto Layout | CSS Gerado | | ----------------- | -------------------------------- | | Horizontal | flex-direction: row | | Vertical | flex-direction: column | | Space between | justify-content: space-between | | Packed (center) | justify-content: center | | Gap: 16 | gap: 16px ou $spacing-md | | Padding | padding: Xpx Ypx |

Sem Auto Layout: Elementos recebem position: absolute baseado nas constraints.

Nomenclatura de Elementos Internos

Use nomes descritivos para que o PromptUI gere HTML5 semântico:

| Nome no Figma | HTML Gerado | | -------------------- | ------------------------------------------------ | | field-email | <input type="email" placeholder="Email"> | | field-password | <input type="password" placeholder="Password"> | | field-cpf | <input type="text" placeholder="Cpf"> | | field-telefone | <input type="tel" placeholder="Telefone"> | | btn-enviar | <button> | | link-esqueci-senha | <a href="/esqueci-senha"> | | nav-menu | <nav> | | img-avatar | <img alt="Avatar"> |

Classificação de Componentes

O PromptUI usa HTML5 Semântico + Atomic Design + SOLID para classificar componentes automaticamente.

Átomos (Elementos Indivisíveis)

Elementos simples, sem filhos complexos:

button, btn, link, input, field, textfield, textarea, select,
checkbox, radio, toggle, switch, icon, image, img, avatar,
badge, tag, chip, label, text, spinner, loader, loading,
skeleton, progress, divider, separator, spacer, line

Exemplos: #Button, #Input, #Icon, #Badge, #Avatar

Moléculas (Combinação de Átomos)

Formam unidade funcional:

card, tile, item, row, cell, form, fieldset, form-group,
input-group, search-bar, nav, menu, navbar, nav-bar, nav-item,
breadcrumb, tabs, tab, modal, dialog, popup, popover, tooltip,
dropdown, alert, toast, notification, snackbar, banner,
list-item, menu-item, accordion-item, figure, thumbnail

Exemplos: #Card, #Form, #SearchBar, #Modal, #Alert

Organismos (Seções Estruturais HTML5)

Contêm moléculas, são seções completas:

header, footer, main, section, article, aside, sidebar, panel,
container, wrapper, list, grid, table, gallery, carousel,
hero, features, testimonials, pricing, contact, wizard, stepper,
flow, timeline, dashboard, overview, stats, screen, page, view,
layout, template

Exemplos: #Header, #Footer, #Sidebar, #LoginScreen, #Dashboard

Regra de Composição

Se um componente tem filhos marcados com #, ele é automaticamente um ORGANISMO.

#LoginScreen          → organismo (tem #Header, #Form, #Footer como filhos)
├── #Header           → organismo (pelo nome)
├── #Form             → molécula (pelo nome)
│   └── #Button       → átomo (pelo nome)
└── #Footer           → organismo (pelo nome)

HTML5 Semântico

Tags Geradas Automaticamente

| Padrão no Nome | Tag HTML | | --------------------------- | ---------------- | | button, btn | <button> | | input, field, campo | <input> | | link, anchor | <a href="..."> | | nav, menu, navegacao | <nav> | | header, cabecalho | <header> | | footer, rodape | <footer> | | section, secao | <section> | | article, artigo | <article> | | image, imagem, avatar | <img> | | form, formulario | <form> | | (padrão) | <div> |

Tipos de Input Detectados

| Nome do Campo | Tipo Gerado | | ------------------------------- | ----------------- | | field-email, campo-email | type="email" | | field-password, campo-senha | type="password" | | field-telefone, field-phone | type="tel" | | field-busca, field-search | type="search" | | field-numero, field-number | type="number" | | field-data, field-date | type="date" | | field-url, field-website | type="url" | | field-arquivo, field-upload | type="file" | | (outros) | type="text" |

Placeholders Genéricos

O placeholder é gerado automaticamente a partir do nome do campo:

field-cpf       → placeholder="Cpf"
field-cnpj      → placeholder="Cnpj"
campo-nome      → placeholder="Nome"
input-endereco  → placeholder="Endereco"

Como Funciona

O PromptUI segue um pipeline de 4 etapas:

┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   1. FETCH   │ ──► │   2. PARSE   │ ──► │  3. CODEGEN  │ ──► │   4. WRITE   │
│  API Figma   │     │  Estrutura   │     │  Framework   │     │  Arquivos    │
└──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘

Etapa 3: Geração de Código

Gera código específico para cada framework:

React + SCSS (BEM):

export const Button = ({ children, className = "" }: IButtonProps) => {
  return (
    <button className={`button ${className}`.trim()}>
      <span className="button__label">{children}</span>
    </button>
  );
};

.button {
  display: flex;
  align-items: center;
  gap: $spacing-xs;
  padding: $spacing-sm $spacing-lg;
  background-color: $color-primary;
  border-radius: $radius-medium;
}

Design Tokens SCSS (_variables.scss):

// Cores extraídas do Figma
$color-primary: #3b82f6;
$color-primary-hover: #2563eb;
$color-secondary: #64748b;
$color-success: #22c55e;
$color-warning: #f59e0b;
$color-error: #ef4444;
$color-background: #ffffff;
$color-surface: #f8fafc;
$color-text-primary: #1e293b;
$color-text-secondary: #64748b;
$color-border: #e2e8f0;

// Espaçamentos (baseado no gap/padding do Figma)
$spacing-xs: 4px;
$spacing-sm: 8px;
$spacing-md: 16px;
$spacing-lg: 24px;
$spacing-xl: 32px;
$spacing-2xl: 48px;

// Border Radius
$radius-none: 0;
$radius-small: 4px;
$radius-medium: 8px;
$radius-large: 12px;
$radius-xl: 16px;
$radius-full: 9999px;

// Tipografia
$font-family-sans: "Inter", -apple-system, BlinkMacSystemFont, sans-serif;
$font-family-mono: "Fira Code", monospace;

$font-size-xs: 12px;
$font-size-sm: 14px;
$font-size-base: 16px;
$font-size-lg: 18px;
$font-size-xl: 20px;
$font-size-2xl: 24px;
$font-size-3xl: 30px;

$font-weight-normal: 400;
$font-weight-medium: 500;
$font-weight-semibold: 600;
$font-weight-bold: 700;

// Sombras
$shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
$shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
$shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1);
$shadow-xl: 0 20px 25px rgba(0, 0, 0, 0.15);

// Transições
$transition-fast: 150ms ease;
$transition-normal: 200ms ease;
$transition-slow: 300ms ease;

Tailwind CSS:

export const Button = ({ children, className = "" }: IButtonProps) => {
  return (
    <button
      className={`flex items-center gap-2 px-6 py-3 bg-blue-500 hover:bg-blue-600 text-white rounded-lg transition-colors ${className}`.trim()}
    >
      <span>{children}</span>
    </button>
  );
};

Material UI:

import { Button as MuiButton, Box, Typography } from "@mui/material";

export const Button = ({ children, className = "" }: IButtonProps) => {
  return (
    <MuiButton
      variant="contained"
      className={className}
      sx={{
        display: "flex",
        alignItems: "center",
        gap: 1,
        px: 3,
        py: 1.5,
        borderRadius: 2,
      }}
    >
      <Typography>{children}</Typography>
    </MuiButton>
  );
};

Bootstrap:

export const Button = ({ children, className = "" }: IButtonProps) => {
  return (
    <button
      className={`btn btn-primary d-flex align-items-center gap-2 ${className}`.trim()}
    >
      <span>{children}</span>
    </button>
  );
};

Ant Design:

import { Button as AntButton } from "antd";

export const Button = ({ children, className = "" }: IButtonProps) => {
  return (
    <AntButton
      type="primary"
      className={className}
      style={{
        display: "flex",
        alignItems: "center",
        gap: 8,
        height: "auto",
        padding: "12px 24px",
        borderRadius: 8,
      }}
    >
      {children}
    </AntButton>
  );
};

Flutter:

class Button extends StatelessWidget {
  final Widget child;
  final VoidCallback? onPressed;

  const Button({Key? key, required this.child, this.onPressed}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: onPressed,
      style: ElevatedButton.styleFrom(
        padding: const EdgeInsets.symmetric(horizontal: 24, vertical: 12),
        shape: RoundedRectangleBorder(
          borderRadius: BorderRadius.circular(8),
        ),
      ),
      child: child,
    );
  }
}

SwiftUI:

struct Button: View {
    let label: String
    let action: () -> Void

    var body: some View {
        SwiftUI.Button(action: action) {
            Text(label)
                .padding(.horizontal, 24)
                .padding(.vertical, 12)
                .background(Color.blue)
                .foregroundColor(.white)
                .cornerRadius(8)
        }
    }
}

Integração com Claude Code

O PromptUI inclui um Agente MCP (Model Context Protocol) para integração com IA.

Configuração

# Inicie o agente
npx @promptui-lib/cli agent

Configure no Claude Code:

{
  "mcpServers": {
    "promptui": {
      "command": "npx",
      "args": ["@promptui-lib/cli", "agent"]
    }
  }
}

Exemplos de Prompts

"Gere o componente #Button do Figma usando Tailwind"
"Gere todos os componentes marcados com Material UI"
"Sincronize os design tokens para variáveis SCSS"
"Preview do #LoginForm sem salvar"

Autor

Desiree Menezes - @desireemenezes

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Índice

O que é o PromptUI?

Principais Funcionalidades

Início Rápido

Instalação

Frameworks Suportados

Comandos CLI

Gerar Componentes

Opções

Outros Comandos

Configuração

Obtendo Credenciais do Figma

Entendendo o fileId vs node-id

Guia para Designers

Regra Principal: Prefixo #

Composição de Componentes

Auto Layout é Essencial

Nomenclatura de Elementos Internos

Classificação de Componentes

Átomos (Elementos Indivisíveis)

Moléculas (Combinação de Átomos)

Organismos (Seções Estruturais HTML5)

Regra de Composição

HTML5 Semântico

Tags Geradas Automaticamente

Tipos de Input Detectados

Placeholders Genéricos

Como Funciona

Etapa 3: Geração de Código

Integração com Claude Code

Configuração

Exemplos de Prompts

Autor

Licença

Regra Principal: Prefixo `#`