Figmagic é a peça perdida entre DevOps e design: Gerador de tokens de design, exporta gráficos, e extrai componentes React acionados por tokens para os seus documentos Figma.
🏕️ Kumbaya, amigos. Figmagic automatiza o mundo para um lugar melhor, mas não pode remover completamente designers e desenvolvedores: utomates the world into a better place, but does not attempt to completely remove designers or developers: O objetivo é apenas aproximar-se disso, enquanto eliminamos a maioria do trabalho tedioso que cresce em torno do desenvolvimento front-end.
Construído inicialmente como uma ferramenta de transferência interna para Humblebee.
Versões anteriores à 4.0 estão sendo usadas trash para lidar com arquivos que precisam ser substituídos. Na versão 4.3.0 esse não é mais o caso.
Quaisquer arquivos deletados, agora serão destruídos permanentemente pelo módulo ativo do Node fs.
As versões 4.3.0 e 4.3.1 usam um modo duplo fragmentado, padrão configurável onde você pode usar um padrão "hard" ou "soft" de exclusão (exclusões sof significam substituir arquivos em uma pasta de lixeira local). This is NOT supported and intended from 4.3.2 and forward as that was too buggy.
Por favor, perceba: Figmagic requere que a sua estrutura de documento siga as convenções nesse documento; um setup inteiro pode ser visto nesse template em https://www.figma.com/community/file/821094451476848226/Figmagic-%E2%80%94-Design-System-for-Tokens.
Figmagic é compilado do Typescript para ES6, então, você deve ter o Node 12 ou uma versão maior (Node 14 e mais novos são recomendados) para funcionar na sua máquina.
Figmagic é uma ferramenta de linha de comando super flexível e muito simples que ajuda você a fazer bem três coisas:
Produzir e usar design tokens auxiliar em projetar com uma abordagem estruturada. Esses tokens são completamente agnósticos de plataforms quando produzidos em JSON, ou para a maiores dos desenvolvedores web, mais acessíveis de uso em vários sabores de Javascript (TS, JS, MJS). É web-orientada mas funciona bem com React Native também.
Uma configuração básica de tokens pareceria com:
const tokens = {
colors: {
blue: 'rgba(20, 20, 255, 1)',
warmWhite: 'rgba(240, 240, 240, 1)'
},
spacing: {
small: '1rem',
medium: '1.5rem'
}
};Você usar esses tokens dessa forma, color: ${colors.blue};, para formar e especificar os seus componentes codados, web sites, apps e o que você tiver, ao invés de código díficil para cada valor.
Desse jeito, você dissocia a implementação de dados. Você pode agora facilmente dirigir as mudanças como design choices através do Figma ao invés de code changes.
Diga adeus para sempre a exportar gráficos manualmente do Figma de novo. Pegue seus gráficos como PNG, SVG, como componentes React com SVG inline, ou como objetos que exportam todos os gŕaficos de um único arquivo.
Figmagic também permite a geração de componentes React de componentes Figma que seguem uma estrutura formal específica. É razoavelmente o melhor para componentes de baixo nível que você pode montar para fazer organismos mais complexos. Você pode ter uma rotatividade padrão e tempo de programação com o Figmagic.
E, não, o código não é uma droga! Essa era a minha maior queixa com serviços que prometem essa funcionalidade, então eu sabia que tinha que ser bom, ou pelo menos tolerável. Portanto, o Figmagic suporta coisas como usar seus próprios tokens (então nós podemos cortar o código pesado pro lixo, a menos que as correspondências não sejam encontradas) e você pode customizar completamente o número de arquivos relacionados gerados.
Enquanto não for perfeito, é definitivamente melhor que muitas coisas que eu já vi, feito por grandes companhias. Tudo isso é explicado mais tarde aqui na documentação.
Aqui há algumas razões para você preferir o uso do Figmagic do que outra coisa similar:
- No Figmagic, design tokens são o conceito classe número um desde o primeiro dia
- Figmagic é orientado para o design, desde que o Figma é visto como fonte da verdade
- Figmagic é automatizável e bem leve (~45kb comprimidos), sem dependências externas
- Figmagic é amigável para desenvolvedores e faz algumas premissas no seu uso e/ou setup e suporta uma variedade de formatos de output maior que é expansível através de templates customizados se você precisar de algo completamente diferente
- Figmagic é open-source sobre a licença MIT e tem um longo histórico de pequenos ciclos de implementações para novas features/fixes
- Componentes React gerados se ligam a qualquer valor de token que você definir, então eles são igualmente úteis como código inicial ou qualquer código que você produza continuamente
As documentações do Figmagic para desenvolvedores são auto geradas a cada push e podem ser encontrados na documentação dedicada ao site.
Para maiores informações sobre Elementos Figmagic e sincronização deles, veja a página dedicada ao README.
Em adição ao Figmagic, existem muitos outros repositórios/projetos que o cercam:
figmagic-example: Esse repositório é uma demonstração do Figmagic. Nesse projeto você vai ver como um projeto rodando Webpack, React e Styled Components pode usar tokens. Veja mais a seguir!figmagic-action: Figmagic GitHub action. Use Figmagic para recuperar tokens, gráficos e/ou componentes React de um documento Figma.demo-figmagic-action: Demonstração do GitHub action.figma-plugin-continuous-design: Continuous Design é um plugin do Figma que deixa você rodar GitHub Actions, Bitbucket Pipelines, and Azure DevOps Pipelines no Figma.automator-figmagic: Mac OS X serviço automatizado para Figmagic.
Um exemplo de projeto usando React, Styled Components e Storybook-está disponível em https://github.com/mikaelvesavuori/figmagic-example.
Note that this demo is not meant to fully style and do all of the things in the Figma document. I wanted to straddle a middle-of-the-road solution where I did the least work possible to get it working with React and style only a few of the most obvious and helpful elements, like setting disabled state on the button and checkbox.
Figmagic Example Demo: Na esquerda é um grande componente Figma montado num número de "Elementos", o compilador de componentes do Figmagic pode ter um output no código. Na direita é uma versão de um componente React depois de alguns minutos de código e fechamento de elementos corretos.
Rode npm install -g figmagic ou yarn global add figmagic.
Uso local é possível instalando o Figmagic como uma dependência de desenvolvedor (debaixo de devDependencies) com npm install figmagic -D ou yarn add figmagic -D, então usando um script apontando para a versão local, como:
"scripts": {
"figmagic": "npx figmagic"
}
Figmagic pode ser rodado sem nenhuma configuração. Você sempre vai precisar expecificar sua API de token do Figma e seu documento de ID do Figma, no entanto! Apesar disso, é altamente recomendado adicionar uma configuração: é fácil e te dá uma tonelada de de possibilidades para otimizar suas necessidades.
Rode figmagic init para iniciar um arquivo de configuração básica, nomeie-o figmagic.json ou .figmagicrc. Contanto que você forneça seu token ou documentação ID/URL do Figma, o novo arquivo gerado está proto para ser usado pelo Element Sync que só pode ser feito se os seus pontos de configuração tiverem um código válido de geração de templates (é o que o gerado faz). Você verá que a configuração aponta de templates.templatePath{Graphic|React|Styled|Storybook} para ./node_modules/figmagic/templates/{graphic|react|styled|story}. Leia mais em Seção de arquivo de configuração.
Primeiro de tudo, pegue o seu token da API e sua URL do Figma:
- Pegue o seu arquivo ID clicando com o botão direito na sua aba do Figma dentro do app e clique em
Copiar Link—o primeiro, long junk-looking bit is the ID. - Para mais sobre chaves de API, vá para a documentação para desenvolvedores do Figma.
Pass in your Figma API token and Figma URL by either:
- Stepping into your project directory (where you want Figmagic to run), and add or replace FIGMA_URL and FIGMA_TOKEN in a
.envfile with your own file ID (i.e. similar to821094451476848226) or full Figma URL (i.e. similar tohttps://www.figma.com/file/821094451476848226/Figmagic-%E2%80%94-Design-System-template-4.0) and API token key. - Passing in API token and URL through the CLI, like this
figmagic --token {TOKEN} --url {URL}(substitute curly braces for your actual values) - Setting them in
figmagic.json/.figmagicrcundertokenandurl. This is discouraged since you will display these values in clear text and you probably don't want that.
Then:
- Run
figmagic - You should now have a folder with the raw JSON dump (default:
/.figmagic) and a folder with tokens (default:/tokens) in the root
Nomes de pastas seguem por padrão seus nomes. A renomeação é possível através de configuração.
.figmagicvai conter o JSON extraído e recuperado da API do Figmatokensvai conter os arquivos de tokenselementsvai conter os códigos geradosgraphicsvai conter gráficos
Para uma descrição mais completa da estrutura de código, veja a seção de estrutura de código.
Vá para https://www.figma.com/community/file/821094451476848226/Figmagic-%E2%80%94-Design-System-for-Tokens e faça sua própria cópia. Vá em frente usando seu documento ID como a FIGMA_URL ou comece copiando em seu próprio trabalho.
Sua estrutura precisa seguir o seguinte:
- Uma página precisa existir, chamada
Design tokens. Sem essa página, você não pode fazer muito com o Figmagic. - Seguindo, dentro da página
Design tokens, frames precisam existir. Você pode ter qualquer número de token frames suportado. Para iniciantes, nomeie eles comoColors,Font sizes,Font families,Font weights,Line heights, eSpacing– a cobertura exata não é importante, entretanto spelling is important! Para uma lista cheia de tipos de token, veja os tipos de design tokens que o Figmagic pode extrair. - Todos os items em uma página precisam ser guardados por um ou mais frames.
- Quer sincronização de elementos? Então crie uma pagina "Elements" e coloque quaisquer componentes ali. Para a geração correta, você precisa ter os limites especificados.
Veja um template de design system em https://www.figma.com/community/file/821094451476848226/Figmagic-%E2%80%94-Design-System-template-4.0. Sinta-se livre para simplesmente copiar-colar ou basear seu trabalho através desse.
Note: Refer to the document structure in the image below and in the template linked above.
How a Figmagic project could be structured in regards to tokens, if you want to support all currently available token types.
Design tokens são elementos abstratos e compartilhados para que seu design system seja construído.
Design tokens expressam quaisquer um dos valores individuais que foram construídos para, como cores, espaçamentos, e features de tipografia.
Tokens oferecem uma forma de "contrato" entre as intenções dos designers e o cumprimento pelos desenvolvedores. Isso significa que os dois lados concordam em tratar suas partes individuais de um design completo através dos tokens, que representam esses valores. Como formato, eles são super fáceis de ler e entender e são adaptáveis para consumo por muitos tipos de sistemas ou aplicações. Isso é muito importante quando se começa com apps cross-platforms e coisas como isso.
Tokens garantem que os valores não são números mágicos ou "apenas escolhidos aleatoriamente". Isso faz com que a comunicação seja precisa e sem esforço. Criar código para componente, mesmo complexos, pode ser muito menos chato, desde que o que você esteja fazendo esteja apontando para coisas como padding, z index, e qualquer outra coisa que os tokens possam representar.
Portanto: Você pode continaur querendo adicionar um guia para uso. É apenas que os tokens deveriam ser capazes de serem consumidos sem entender nada específico sobre eles.
Você deve vincular os tokens aos estilos do Figma quando e onde for possível para simplificar o seu trabalho de design, mas tenha certeza que isso também está representado na página de Tokens , já que nessa página que um desenvolvedor irá pegar os tokens com o Figmagic.
Atualmente você pode extrair design tokens de:
- Cores (incluindo lineares e gradientes radiais, note que: gradientes lineares que não usam ângulos retos vão ter um cálculo incorreto)
- Tamanhos de fontes
- Espaçamento
- Peso de Fontes
- Altura das linhas
- Famílias de fontes
- Espaçamento entre letras
- Z index
- Radii
- Tamanhos de bordas
- Sombras (atualmente suporta únicos/mútiplos Drop Shadows, see caveat below)
- Opacidades
- Durações (para animações)
- Delays (para animações)
- Easing functions (para animações)
- Media Queries
Um típico caso de uso para documentos gerados é alimentar os valores extraídos do sistema de CSS que suporta valores externos (como Styled Componentes, Emotion, Styled System, e quaisquer outras CSS-in-JS bibliotecas, ou até talvez Sass).
De alehar9320 comentado na issue 111:
Figma calls everything Drop-shadow, while translating the design into box-shadow or drop-shadow CSS dependent upon whether it's a ~ shape or a vector graphic. See blog post from the Figma developer who built the feature.
This means that if Figmagic is used to define shadow tokens, it should be recommended to only have one drop-shadow definition per rectangle. To maintain compatibility with both drop-shadow and box-shadow CSS. The exception would be if there is a clear distinction between tokens to be used with box-shadow and drop-shadow. As drop-shadow can only accept a single shadow parameter. Any token that has two values will simply be incompatible with drop-shadow.
Estilos do Figma se tornaram disponíveis públicos em Junho de 2018 e estão disponíveis para designers criarem single-sources-of-truth quando começarem com valores de design (tokens). Quando se está usando o Figmagic no entenado, o pensamento e usabilidade é um pouco diferente de como os estilos do Figma funcionam.
Um estilo do figma é multidimensional: contém um número de propriedades envolto em um estilo, agindo como uma espécie de pacote. Isso é acessível num desenvolvimento de design e é prático para pontos de vista dos usuários. O usuário não precisa pensar muito sobre valores de armazenamento "redundante" que são o mesmo em outros componentes, como N números de unidades para altura de linhas: Eles são todos muito cuidadosos.
O Figmagic expressa os tokens como instâncias de cada valor individual portanto sendo unidimensional - significa que eles armazenam apenas um valor por item. Exemplos podem ser setados em alturas de linhas, peso de fontes ou tamanhos de fontes, cada um é especificado individualmente. O que isso envolve para o desenvolvedor e o designer, é que valores podem ser usados e misturados em vários contextos, não ficando preso a um contexto específico como um cabeçalho. Para um desenvolvedor, isso é bom porque nós preferimos mapear os valores definitivos para algo, para um componente (um "contexto" por assim dizer).
Por causa dessa diferença, o jeito apropriado de estruturar o Figmagic-documento de design compatível com o Figma é mostrar um ou mais items/tokens nos respectivos frames que correspondem aos tipos de tokens aceitos (altura de linha, tamanho da fonte...) onde cada item tem um tipo de propriedade chave que é mudada entre elas (como um texto usando tamanho 58, outro usando tamanho 40), desde que esses items sejam loops do Figmagic quando criados novos códigos de tokens.
Um dos maiores desvios do principal são as "Fontes" onde você pode especificar mais propriedades que uma. Entretanto, elas precisam corresponder individualmente a outros tokens tipográficos que você possar ter, como altura de linhas.
The "Heading L" font token is composed of values that are also represented in the "lesser" uni-dimensional tokens: displayed here are "Line Height S" (135% line height), "H1" (size 48), and "Font Bold" (Bold font style). Setting this font as a Figma Style will make your life as a designer much easier as your apply the text style to things. Auto-generating code with Figmagic will also work just fine, since the individual values are respected.
O que for melhor para você! Com tanto que você lembra que o Figmagic busca aqueles valores (unidimensionais) para cada design items/tokens tudo deverá funcionar. Eu já vi estilos do Figma que fazem um "contrato" entre tokens e seus espaços de trabalho do dia-a-dia com designers muito mais fácil. De novo portanto, Figmagic não usa esses valores; pense neles como uma cola conveniente.
Por padrão está ligado. Você vai precisar ter uma pagina de nome "Design tokens", onde com os seus tokens frames nomeados.
Tokens são o "pão e a manteiga" of Figmagic. Sem tokens, Figmagic não pode criar elementos. E mesmo sem elementos, os tokens fornecem toda a experiência para ajudar você com um design system compentente e sem código.
No caso de você querer pular para um frame dado, você pode adicionar um sublinhado principal ao nome do frame. Você também pode pular items individuais nomeando-os com ignore ou adicionando um sublinhado principal.
Isso é ativado por padrão, mas agora é possível desativar se você tem razões bem específicas para.
Por padrão isso está desligado. Passe --syncGraphics como uma flag para sincroniza-los ou habilita-los no seu arquivo de configuração. Você vai precisar ter uma página com o nome "Graphics", onde seus componentes serão adicionados diretamente.
Gráficos podem ser exportados em múltiplos formatos com o Figmagic. Ao inveś de fazer a entrega manual, apenas diga aos desenvolvedores que tiveram atualizações aos gráficos e deixem eles darem um pull as últimas versões do documento do Figma.
Novamenteo, dê uma olhada no template em https://www.figma.com/community/file/821094451476848226/Figmagic-%E2%80%94-Design-System-for-Tokens para referência.
Isso também fica desligado por padrão. Passe --syncElements ou ative no seu arquivo de configuração para gerar código para os seus componentes Figma.
Upcoming versions of Figmagic may attempt to support Figma Variants, but that will have to be publicly released first, and then vetted against what Figmagic can generate before I commit to supporting that model. Until then, the existing mental model of "Elements" will continue to be used.
Elementos são nomeados porque são destinados principalmente a ajduar na programação que mapeia por padrão elementos HTML como input, button, h1, e form. Com programação nós queremos dizer esses elementos que podem ser gerados como código num formato que preenche para continuaçao do desenvolvimento. Elementos podem ser um bom ponto de entrar para ambos, design e geração de código, desde que eles sejam relativamente simples como conceitos mapeados no HTML, o que retorna o embasamento em tags ("elementos").
Elementos são gerados passando sua estrutura de componentes do Figma em qualquer variedade "flat" ou "nested". Quaisquer valores, diremos uma altura de 48px e uma cor específica azul, vai tentar ser entregue como derivada de um token relevante. Portanto, sem tokens, elementos não podem ser gerados! Nesse exemplo, talvez a altura vá ser mapeada por um token que usa 48px (mapeada como 3rem onde 3 x 16 = 48, com 16 sendo o valor padrão de REM) e a cor poderia ser mapeada como cor nos tokens de cores.
If you need more information and guidance on this, see the dedicated documentation section at Figmagic Element Sync.
Há muitas formas com as quais você pode fornecer o Figmagic com conhecimento sobre como você passará seus tokens. Você pode combinar eles, mas cuidado com a priorização do gráfico (do menor para o maior):
- Configurações fornecidas pelo usuário pelo arquivo
figmagic.json/.figmagicrc - Variavéis de desenvolvimento (também carregadas no arquivo
.env) - Argumentos de linhas de comando e flags
Se possível, fixe um jeito de providenciar as confiurações.
Valores não providenciados vão voltar para os padrões em bin/entities/Config/baseConfig.ts.
Você pode usar um JSON formatado como arquivo de configuração na raíz do projeto para usar as configurações. Figmagic vai pegar pelo caminho avaliando o trabalho atual no diretório e olhando também para os arquivos figmagic.json ou .figmagicrc . Se achá-los, vai usá-los.
Um exemplo de arquivo é fornecido no Figmagic-você pode encontrar na raíz do projeto. O arquivo se chama figmagicrc, apenas adicione o ponto principal e coloque o arquivo na pasta do seu próprio projeto para usar. Para usar como JSON, adicione json no final do arquivo.
Como é um arquivo de configuração, você precisa ser cuidadoso em escrever corretamente ou você pode terminar com falhas e erros.
Abaixo está um conjunto completo do que você pode configurar, junto com os padrões.
{
"debugMode": false,
"fontUnit": "rem",
"letterSpacingUnit": "em",
"lineHeightUnit": "unitless",
"opacitiesUnit": "float",
"figmaData": "figma.json",
"figmagicFolder": ".figmagic",
"outputFolderElements": "elements",
"outputFolderGraphics": "graphics",
"outputFolderTokens": "tokens",
"outputFormatColors": "rgba",
"outputFormatCss": "ts",
"outputFormatDescription": "md",
"outputFormatElements": "tsx",
"outputFormatGraphics": "svg",
"outputFormatStorybook": "js",
"outputFormatTokens": "ts",
"outputGraphicElements": false,
"outputGraphicElementsMap": false,
"outputScaleGraphics": 1,
"outputDataTypeToken": null,
"overwrite": {
"css": false,
"description": false,
"graphic": false,
"react": false,
"storybook": false,
"styled": false
},
"recompileLocal": false,
"refreshType": "soft",
"remSize": 16,
"skipFileGeneration": {
"forceUpdate": true,
"skipCss": false,
"skipDescription": false,
"skipReact": false,
"skipStorybook": false,
"skipStyled": false
},
"spacingUnit": "rem",
"syncElements": false,
"syncGraphics": false,
"syncTokens": true,
"templates": {
"templatePathGraphic": "templates/graphic",
"templatePathReact": "templates/react",
"templatePathStorybook": "templates/story",
"templatePathStyled": "templates/styled"
},
"token": "",
"unitlessPrecision": 2,
"url": "",
"usePostscriptFontNames": false,
"versionName": null
};Rode esses comandos no ambiente de linha de comando a sua escolha.
figmagic [--debug | -d]
Default: false.
figmagic [--fontUnit | -fu] [rem|em|px]
Default: rem.
figmagic [--letterSpacingUnit | -lsu] [em|px]
Default: em.
figmagic [--lineHeightUnit | -lhu] [unitless|em|px|rem]
Default: unitless.
figmagic [--opacitiesUnit | -ou] [float|percent]
Default: float.
figmagic [--figmaData | -file] [filename]
Default: figma.json.
figmagic [--figmagicFolder | -base] [folder]
Default: .figmagic.
figmagic [--outputFolderElements | -elements] [folder]
Default: elements.
figmagic [--outputFolderGraphics | -graphics] [folder]
Default: graphics.
figmagic [--outputFolderTokens | -tokens] [folder]
Default: tokens.
figmagic [--outputFormatColors | -fcol] [hex|rgba]
Default: rgba.
Isso apenas de aplica a cores sólidas; gradientes vão continuar usando cores RGBA.
Hex color support may potentially interfere with element generation and binding to tokens, since RGB(A) is the format that Figma itself uses, so there is a slight possibility of mismatches in the Figmagic binding process.
Note that hex colors will not use any alpha/transparency!
figmagic [--outputFormatCss | -fc] [ts|mjs|js]
Default: ts.
figmagic [--outputFormatDesc | -fd] [md|txt]
Default: md.
figmagic [--outputFormatElements | -fe] [tsx|jsx|mjs|js]
Default: tsx.
figmagic [--outputFormatGraphics | -fg] [svg|png]
Default: svg.
figmagic [--outputFormatStorybook | -fs] [ts|js|mdx]
Default: js.
figmagic [--outputFormatTokens | -ft] [ts|mjs|js|json|css]
Default: ts.
figmagic [--outputGraphicElements | -oge]
Default: false.
figmagic [--outputGraphicElementsMap | -ogm]
Default: false.
figmagic [--outputScaleGraphics | -scale] [number]
Default: 1.
Note that from the CLI you must specify the scale size like 3x (or anything at the end, as long as it includes a letter at the end). This only applies to CLI configuration, and does not apply to other types of config, such as through figmagic.json or .figmagicrc.
figmagic [--outputDataTypeToken | -tokentype] [null | enum]
Default: null.
This is not currently possible to adjust from the CLI.
figmagic [--recompileLocal | -local]
Default: null, and will then be taken from local .env file if not explicitly passed in through the CLI.
figmagic [--remSize | -rem] [number]
Default: 16.
Note that from the CLI you must specify the REM size like 16p (or anything at the end, as long as it includes a letter at the end). This only applies to CLI configuration, and does not apply to other types of config, such as through figmagic.json or .figmagicrc.
figmagic [--forceUpdate | -force]
Default: true.
Forces all elements and file types to be regenerated.
figmagic [--skipCss | -nocss]
Default: false.
Skip creating CSS file when syncing elements.
figmagic [--skipDescription | -nodesc]
Default: false.
Skip creating Markdown file when syncing elements.
figmagic [--skipReact | -noreact]
Default: false.
Skip creating React file when syncing elements.
figmagic [--skipStorybook | -nostory]
Default: false.
Skip creating Storybook file when syncing elements.
figmagic [--skipStyled | -nostyled]
Default: false.
Skip creating Styled Components file when syncing elements.
figmagic [--spacingUnit | -s] [rem|em|px]
Default: rem.
figmagic [--syncElements | -se]
Default: false, and will then be taken from local .env file if not explicitly passed in through the CLI.
Use this when you want to sync elements in your "Elements" page in Figma.
figmagic [--syncGraphics | -sg]
Default: false, and will then be taken from local .env file if not explicitly passed in through the CLI.
Use this when you want to sync graphics in your "Graphics" page in Figma. Use the RC configuration file to pass in options. Default format will be SVG.
figmagic [--syncTokens | -st]
Default: true, and will then be taken from local .env file if not explicitly passed in through the CLI.
Use this when you want to sync tokens in your "Design tokens" page in Figma. Use the RC configuration file to pass in options.
figmagic [--templatePathGraphic | -tpgraphic] [path]
Default: templates/graphic.
Your local figmagic.json or .figmagicrc file must have a block with templates.templatePathGraphic that specifies a valid path, such as ./node_modules/figmagic/templates/graphic.
figmagic [--templatePathReact | -tpreact] [path]
Default: templates/react.
Your local figmagic.json or .figmagicrc file must have a block with templates.templatePathReact that specifies a valid path, such as ./node_modules/figmagic/templates/react.
figmagic [--templatePathStorybook | -tpstory] [path]
Default: templates/story.
Your local figmagic.json or .figmagicrc file must have a block with templates.templatePathStory that specifies a valid path, such as ./node_modules/figmagic/templates/story.
figmagic [--templatePathStyled | -tpstyled] [path]
Default: templates/styled.
Your local figmagic.json or .figmagicrc file must have a block with templates.templatePathStyled that specifies a valid path, such as ./node_modules/figmagic/templates/styled.
figmagic [--token | -t] [token]
Default: null, and will then be taken from local .env file if not explicitly passed in through the CLI.
figmagic [--tokensRelativeImportPrefix | -tip] [path]
Default: '' (effectively just blank or the same folder). Use this so CSS files can import tokens from the correct location, for example to resolve something like ../../tokens/colors.ts you would pass in ../../ and tokens would be whatever your outputFolderTokens value is.
figmagic [--url | -u] [url_id]
Default: null, and will then be taken from local .env file if not explicitly passed in through the CLI.
figmagic [--unitlessPrecision | -up] [number]
Default: 2.
Defines the precision (decimals) for unitless values (rounded using .toFixed() internally).
figmagic [--usePostscriptFontNames | -ps]
Default: false, i.e. common name.
figmagic [--useLiteralFontFamilies | -lff]
Default: false, i.e. uses common name or Postscript name applied to the Figma's frame.
That's particularly useful for defining the whole font family stack with the fallbacks instead of a single font name, i.e.: Roboto, BlinkMacSystemFont, Helvetica, Arial, sans-serif
figmagic [--versionName | -v]
Default: null which will resolve to the latest version. The value you specify here is the name of the version in the Figma file's Version history.
From version 4.5.8, you can also export color themes tokens.
Consider the following example in Figma, as example of an app that allows the user to switch between Dark Theme and Light Themes for enhancing accessibility:
It will translate into the following generated tokens:
const colors = {
black: 'rgba(51, 51, 51, 1)',
white: 'rgba(255, 255, 255, 1)',
red: 'rgba(235, 87, 87, 1)',
blue8: 'rgba(47, 128, 237, 1)',
green6: 'rgba(33, 150, 83, 1)',
darkTheme: {
emptyShade: 'rgba(51, 51, 51, 1)',
fullShade: 'rgba(255, 255, 255, 1)',
mediumShade: 'rgba(189, 189, 189, 1)',
darkShade: 'rgba(224, 224, 224, 1)',
danger: 'rgba(248, 102, 102, 1)',
warning: 'rgba(246, 212, 107, 1)',
primary: 'rgba(39, 131, 255, 1)',
success: 'rgba(68, 239, 141, 1)'
},
lightTheme: {
fullShade: 'rgba(51, 51, 51, 1)',
emptyShade: 'rgba(255, 255, 255, 1)',
darkShade: 'rgba(130, 130, 130, 1)',
mediumShade: 'rgba(189, 189, 189, 1)',
danger: 'rgba(235, 87, 87, 1)',
warning: 'rgba(242, 201, 76, 1)',
primary: 'rgba(47, 128, 237, 1)',
success: 'rgba(33, 150, 83, 1)'
}
};Which in a practical example you could use as follows:
// initialize with default theme
let theme = 'lightTheme';
// Primary action button with white color token and with different primary background color according to the theme
let button = `<button style="background: ${colors[theme].primary}; color: ${colors.white}">Primary Action</button>`;
// Background color that changes according to the theme
let panel = `<div style=`color: ${colors[theme].emptyShade}`>Panel background</div>`Note on Components generation
Please note that component generation using the --syncElements options doesn't support color tokens yet. In case you have a component with a color that only exists on the colors -> color theme frame Figmagic will warn about: "No matching token! Hard-coding to expected value". Which means, that the component will still be created, just without a token assigned to it the color, since it currently only looks for the Colors frame and not for nested frames.
Starting with Figmagic version 4.0, four types of generated files have customizable templates:
- Graphic elements
- React elements
- Storybook files
- Styled Components (React) files
These four types have support for a variety of formats that differ a bit between each type.
Figmagic comes with a set of templates for several file formats. In case you want to customize these, you should respect and keep any substitution tags that exist in the original files; removing them may cause your templates to function incorrectly. For example, the React template includes a substitution tag called {{NAME_STYLED}} which will be changed to your adjusted element name with a "Styled" suffix. Removing it would make your generated code useless as-is.
The recommended way of adding and using your own templates would be to copy-paste any/all existing templates from Figmagic into your project, pointing the configuration file to your local copies, and then modifying them as needed.
The font family name, either as its common name (as picked up by Figma; spaces are removed) or its Postscript name (eg. FiraSans-Regular).
Default: Common name.
Note: In previous versions of Figmagic the Postscript font family name was used.
Typical font weight values like 200, 300 etc.
Units based on global font size (base 16px).
Default: rem units. Can be set to rem or em.
Unitless.
2 decimals numbered values by default. Precision can be configured with unitlessPrecision (see config)
Default: rgba. Can be set to rgba or hex.
Default: rem units. Can be set to rem or em.
Default: px units.
Default: em units.
Default: px units.
Typical 2 decimals numbered values between 0 and 1 like 0 or 0.65.
Can be set to percent to have them converted to % strings instead like 0% or 65%.
Default: px units.
Default: px units for three values (horizontal offset, vertical offset, blur) and RGBA for the color.
Default: numbers (whole numbers, i.e. integers).
| Folder | Description |
|---|---|
__tests__/ |
Tests, structured similarly to the bin folder source code |
.github/ |
GitHub files for CI and issue template |
.husky/ |
Husky pre-commit configuration |
.vscode/ |
Visual Studio Code configuration |
bin/ |
Source code |
bin/contracts |
Types and interfaces |
bin/controllers |
Controllers |
bin/entities |
Entities (DDD-style), this is where most of the logic will be contained |
bin/frameworks |
Non-domain functionality, like string manipulation and downloading files etc. |
bin/usecases |
Where the application "features" are orchestrated, as per Clean Architecture |
build/ |
ES6-compiled code (this is the code that consumers of the Figmagic binary actually use) |
images/ |
Documentation, mostly images and screen shots. You can manually generate the Arkit diagram with npm run docs. |
readme/ |
Additional readme files |
templates/ |
Files that are used as templates for code generation |
testdata/ |
Most of the tests point to stored test data which is stored in this folder |
typedoc-docs/ |
Documentation generated by TypeDoc, which gets hosted at https://docs.figmagic.com. You can manually generate these with npm run docs. |
index.ts |
The file that initializes and sets up everything required to run Figmagic |
This is how Arkit models Figmagic and its source code structure and dependencies. Note that this diagram omits frameworks, external dependencies and contracts (i.e. types) to focus on the primary flows.
Note! Only visible on the documentation site.
Figmagic is licensed under the MIT License.
It uses a number of developer dependencies under various open source licenses, but none of these are bundled into the actual binary that users consume as Figmagic itself has no end-user-facing dependencies.
Copyright 2018-current Mikael Vesavuori
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
You are welcome to contribute to the project! Pull requests, as well as issues or plain messages, work fine. For pull requests, please refer to the contribution guidelines in CONTRIBUTING.md.
Thanks goes to these wonderful people (emoji key):
 Florent SCHILDKNECHT 💻 |
 Paulo Henrique 💻 |
 Petra Jaros 💻 |
 Marko Marković 💻 |
 mykhailoInnovecs 💻 |
 Zack Brown 💻 |
 Stanko Tadić 💻 |
 Ishmam Chowdhury 💻 |
This project follows the all-contributors specification. Contributions of any kind welcome!