From f1ca8f889ed179bf362e9faee3a92d0da6c6c431 Mon Sep 17 00:00:00 2001 From: Bernardo Raposo Date: Thu, 20 Jun 2019 00:00:21 +0200 Subject: [PATCH] docs: updates docs with more detailed information --- README.md | 166 ++----------------------------------------- docs/examples.mdx | 110 ++++++++++++++++++++++++++++ docs/home.mdx | 40 ++++++++++- docs/quick-start.mdx | 25 ------- docs/road-to-v2.mdx | 109 ++++++++++++++++++++++++++++ 5 files changed, 262 insertions(+), 188 deletions(-) create mode 100644 docs/examples.mdx delete mode 100644 docs/quick-start.mdx create mode 100644 docs/road-to-v2.mdx diff --git a/README.md b/README.md index 342000b..8171cec 100644 --- a/README.md +++ b/README.md @@ -34,174 +34,15 @@ The reimagined [Figma API](https://www.figma.com/developers) (super)powered by G } ``` -## Query examples +## Documentation -Here are some examples of what you can do with the Figma GraphQL API. - -### Get a file's contents - -```gql -{ - file(id: "cLp23bR627jcuNSoBGkhL04E") { - name - thumbnailUrl - lastModified - pages { - name - id - type - frames { - id - name - clipsContent - blendMode - position { - x - y - } - size { - width - height - } - elements(type: "TEXT") { - name - type - characters - position { - x - y - } - size { - width - height - } - style { - fontSize - fontFamily - fontWeight - letterSpacing - } - strokes { - type - } - fill { - r - g - b - a - } - } - } - } - } -} -``` - -### Get just the image of a Node a file or the whole file - -To get the whole file don't pass any more parameters. - -```gql -{ - image(id: "cLp23bR627jcuNSoBGkhL04E") { - images - } -} -``` - -To get the image of node pass the id of that node as a parameter - -```gql -{ - image(id: "cLp23bR627jcuNSoBGkhL04E", params: { ids: "16:19" }) { - images - } -} -``` - -### Get comments on a file - -```gql -{ - comments(id: "cLp23bR627jcuNSoBGkhL04E") { - id - file_key - parent_id - user { - img_url - handle - } - created_at - resolved_at - message - client_meta { - node_offset { - x - y - } - } - } -} -``` - -### Post a comment to a file - -```gql -mutation { - addComment( - id: "cLp23bR627jcuNSoBGkhL04E" - message: "Test from server" - ) { - id - message - } -} -``` - -You can also pass the coordinates where the comment should be placed as a parameter - -```gql -mutation { - addComment( - id: "cLp23bR627jcuNSoBGkhL04E" - message: "Test from server" - params: { x: "12", y: "12" } - ) { - id - message - } -} -``` - -### Get all projects for a team - -```gql -{ - projects(id: "484668844937890483") { - id - name - } -} -``` - -### Get all files for a project - -```gql -{ - projectFiles(project: "420878") { - key - name - thumbnail_url - last_modified - } -} -``` +Please read the [full documentation][website] for additional examples and best practices. ## Developing 1. Clone this repo 2. Run `yarn install` to install all dependencies -3. Run `FIGMA_TOKEN={YOUR_PERSONAL_FIGMA_TOKEN} yarn run dev` +3. Run `FIGMA_TOKEN={YOUR_PERSONAL_FIGMA_TOKEN} yarn run dev` or add it to an `.env` file 4. The Figma GraphQL playground should be available at `http://localhost:3001/` ## Figma file @@ -241,3 +82,4 @@ This project follows the [all-contributors](https://github.com/all-contributors/ [semantic]: https://github.com/semantic-release/semantic-release [greenkeeper-badge]: https://badges.greenkeeper.io/braposo/figma-graphql.svg?style=flat-square [greenkeeper]: https://greenkeeper.io/ +[website]: https://figma-graphql.party diff --git a/docs/examples.mdx b/docs/examples.mdx new file mode 100644 index 0000000..ea66e8d --- /dev/null +++ b/docs/examples.mdx @@ -0,0 +1,110 @@ +--- +name: Practical Examples +route: /practical-examples +--- + +# Practical examples + +Let's look at some practical examples in the perspective of designers, developers and product managers. + +## Designers + +> Get all text styles in a specific frame + +This example tries to follow the structure of the file to get the information we need. + +```gql +{ + file(id: "fileID") { + pages(name: "styles") { + frames(name: "typography") { + groups { + name + texts { + name + styles { + fontSize + fontFamily + fontWeight + ... + } + } + } + } + } + } +} +``` + +> Get the background colours of all the global styles to update their Design System documentation + +We can now use the power of the shortcuts to get that information easily. + +```gql +{ + file(id: "fileID") { + styles(type: FILL) { + name + styles { + color { + r + g + b + } + } + } + } +} +``` + +## Developers + +> Export all icons in a design document to generate up-to-date React components + +We want to export the components in SVG format. + +```gql +{ + file(id: “fileID”) { + pages(name: "Icons") { + components { + name + size { + width + height + } + export(format: svg) + } + } + } +} +``` + +## Product Managers + +> Get the screenshots of the prototype screens for a few different features to present at a product meeting + +We need to go through all the files inside the team projects so we'll be using aliases. + +```gql +{ + projects(teamId: "teamID") { + featureA: files(name: "Feature A") { + pages(name: "Prototype") { + frames { + name + export(format: jpg) + } + } + }, + featureB: files(name: "Feature B") { + pages(name: "Prototype") { + frames { + name + export(format: jpg) + } + } + } + } +} +``` diff --git a/docs/home.mdx b/docs/home.mdx index 403968b..4ec492d 100644 --- a/docs/home.mdx +++ b/docs/home.mdx @@ -7,10 +7,48 @@ route: / # figma-graphql -The reimagined Figma API (super)powered by GraphQL +The reimagined [Figma API](https://www.figma.com/developers) (super)powered by GraphQL [![Build Status][build-badge]][travis] [![Greenkeeper badge][greenkeeper-badge]][greenkeeper] [![Code Coverage][coverage-badge]][coverage] [![Known Vulnerabilities][snyk-badge]][snyk] [![All Contributors](https://img.shields.io/badge/all_contributors-3-orange.svg?style=flat-square)](#contributors) [![PRs Welcome][prs-badge]][prs]
![Prettier format][prettier-badge] [![Commitizen friendly][commitizen-badge]][commitizen] [![semantic-release][semantic-badge]][semantic] [![MIT License][license-badge]][license] +## Quick start + +### 1. Open figma-graphql [sandbox][codesandbox] and fork it + +[![Open figma-graphql][codesandbox-badge]][codesandbox] + +### 2. Add your [Figma API Token](https://www.figma.com/developers/docs#access-tokens) as `FIGMA_TOKEN` in the [codesandbox secret keys](https://codesandbox.io/docs/secrets) + +### 3. Try your first query! + +```gql +{ + file(id: "cLp23bR627jcuNSoBGkhL04E") { + name + } +} +``` + +## Why use figma-graphql? + +It's great that Figma provides an API allowing anyone to easily get the data from their design files. But that API has two characteristics that make it quite hard for people without a good technical knowledge to access it: + +1. The file data has a rigid tree-shaped structure that forces people to know the exact structure of the design file and can easily break existing code by just making a small change in the design file (like grouping elements). + +2. It requires multiple requests to different endpoints to get data that is related. Want to export specific frames in a file? You need to query the file data first, parse the data to get the frame ids and then make additional requests to a different endpoint to get that data. + +This obviously makes things a lot more complex than they need to be so we use the power of GraphQL solve these issues and add a few other features. + +With figma-graphql, we focus on the person using the library, not the machines. We see this as the best way to open your design files to more people, especially to those with minimal technical backround. + +## Examples + +A good way to understand the different queries that you can build is to use the "Schema" tab on the righ-hand side of the playground and go through the different properties of all the supported types, but we've also selected a few [example scenarios](/practical-examples) that can be used as a reference for common uses of the library. + +## Migrating to v2 + +For v2 we've completely rebuilt the API in a more human-first approach which makes it incompatible with most of the v1 queries. To read more about the motivations and biggest changes please read the [Road to v2](/road-to-v2) section. + --- Brought to you by these awesome contributors: diff --git a/docs/quick-start.mdx b/docs/quick-start.mdx deleted file mode 100644 index 88aa11b..0000000 --- a/docs/quick-start.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -name: Quick Start -route: /quick-start ---- - -# Quick Start - -### 1. Open figma-graphql [sandbox][codesandbox] and fork it - -[![Open figma-graphql][codesandbox-badge]][codesandbox] - -### 2. Add your [Figma API Token](https://www.figma.com/developers/docs#access-tokens) as `FIGMA_TOKEN` in the [codesandbox secret keys](https://codesandbox.io/docs/secrets) - -### 3. Try your first query! - -```gql -{ - file(id: "cLp23bR627jcuNSoBGkhL04E") { - name - } -} -``` - -[codesandbox-badge]: https://codesandbox.io/static/img/play-codesandbox.svg -[codesandbox]: https://codesandbox.io/s/github/braposo/figma-graphql/ \ No newline at end of file diff --git a/docs/road-to-v2.mdx b/docs/road-to-v2.mdx new file mode 100644 index 0000000..fd83950 --- /dev/null +++ b/docs/road-to-v2.mdx @@ -0,0 +1,109 @@ +--- +name: Road to v2 +route: /road-to-v2 +--- + +# From v1 to v2 + +We're big fans of [Figma](https://www.figma.com) since pretty much the beginning so when the [API](https://www.figma.com/developers) was announced we immediately jumped on board and created this GraphQL API. That was the first version of the figma-graphql library and it was mostly a 1-to-1 mapping of the existing API. + +As we kept using figma-graphql to get the information from our design files it became evident that the structure of the Figma API response object was very limiting. + +The tree-shaped structure that the REST API uses mimics the same structure of the design file, which makes sense on one hand but on the other hand makes it quite hard for humans to process all that information. + +Besides that, we were completely dismissing the power that GraphQL offers on abstracting multiple requests into a simple query. + +We knew it could be much easier for people to navigate through their design files so we completely rebuilt the library for v2. + +## Shortcuts + +We opted to surface all the different types of elements that are descendants of a given node so it makes the queries much more natural and doesn't force people to know the structure of the design file. + +Let's see a concrete example. This was how we could get the name of a text element in a document: + +```gql +{ + file(id: "cLp23bR627jcuNSoBGkhL04E") { + pages { + frames { + elements(type: "TEXT") { + name + } + } + } + } +} +``` + +We had to follow the structure of the file and know exactly where the element was to get the information we need. This also meant that only the text elements that were direct children of the frames that were at the top level of the page would be returned. + +If the designers grouped the text elements together inside those same frames, we wouldn't be able to return those elements because they'd be a child of a different element now. + +In v2 this is what we can do instead: + +```gql +{ + file(id: "cLp23bR627jcuNSoBGkhL04E") { + pages { + frames { + texts { + name + } + } + } + } +} +``` + +Doesn't seem much of a difference but it fixes most of the issues we had with the previous query. It will return **any** text element that is a child of **any** frame that is part of **any** page in the file. + +In this query `texts`, `frames` and `pages` are shortcuts and don't behave the same way as in v1. These shortcuts respect the query structure so they will only match the nodes that respect the same hierarchy in the document. + +This also means that we could even simplify this query if we just want the name of all the text elements in a file, no matter where they are placed: + +```gql +{ + file(id: "cLp23bR627jcuNSoBGkhL04E") { + texts { + name + } + } +} +``` + +This gives a lot of flexibility and takes away the complexity of the structure of the file from the user by default. + +And that was the main motivation to build the v2 of figma-graphql: to make a human-first API for Figma. + +## Unified query + +Another aspect that we briefly mentioned above is the fact that we weren't taking advantage of the power of abstraction in GraphQL. We had the `file` query but also mapped all the different API end points to separate queries like `images`, `comments`, etc. + +This is still possible and we kept the support from v1, but it's no longer recommended. + +Instead, we are now stitching together the different queries into a single query that can do all the actions supported by the multiple queries in v1 with the added bonus that it makes the queries much easier to understand. + +Let's look at this query for example: + +```gql +{ + projects(teamId: "teamID") { + name + files { + name + frames { + export + } + comments { + message + } + } + } +} +``` + +This is using just the team ID as a starting point to get through all the different projects inside a team, then get all the files for each project and then export all frames from each file in the default jpg format as well as getting all the comments associated with each file. + +It might seem a simple query but it's in fact using four different endpoints and making several requests to get all that information. But it does that in a way that is completely hidden to the user, who doesn't have to deal witht the complexity of the system. + +By making these properties available in their context we make the query much more natural and augment the capababilities of the existing REST API.