Skip to content

Commit

Permalink
docs: updates docs with more detailed information
Browse files Browse the repository at this point in the history
  • Loading branch information
braposo committed Jun 19, 2019
1 parent fc8c141 commit f1ca8f8
Show file tree
Hide file tree
Showing 5 changed files with 262 additions and 188 deletions.
166 changes: 4 additions & 162 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
110 changes: 110 additions & 0 deletions docs/examples.mdx
Original file line number Diff line number Diff line change
@@ -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)
}
}
}
}
}
```
40 changes: 39 additions & 1 deletion docs/home.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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] <br /> ![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:
Expand Down
25 changes: 0 additions & 25 deletions docs/quick-start.mdx

This file was deleted.

Loading

0 comments on commit f1ca8f8

Please sign in to comment.