Accessing Linked Styleguides

Global Styleguides feature lets users organize and update their design system colors, text styles and components all in a centralized location. For a more complex design system, spanning multiple platforms, it's possible to create a system of styleguides which consists of styleguide trees with parent-child relationships. Also, Zeplin projects can be linked to a Global Styleguide so that all colors, text styles, components from the linked styleguide can be referenced in the linked project.

Zeplin API provides access to Global Styleguides from a child styleguide as well as a linked project. This guide shows you how to do that in a few steps since aggregating all related resources of a project is a common pattern.

Accessing all colors from a project

You can get all colors in a project's local styleguide using the "Project colors" endpoint. In addition to local colors, there can be a styleguide linked to the project with more colors as well as a parent styleguide of the linked styleguide that has even more. You can aggregate all colors that the project references in three steps:

Explore related styleguides of the project (linked styleguide and its ancestors)
Fetch the colors of related styleguides
Fetch the colors of the project

Let's say there is a project with 3 colors and it is linked to a styleguide. The linked styleguide contains 2 colors and it has a parent styleguide with 1 color.

Exploring related styleguides of the project

You can fetch related styleguides of the project with this request:

curl https://api.zeplin.dev/v1/styleguides?linked_project=:pid -H 'Authorization: Bearer <access_token>'

Example response:

[
    {
        "id": "5e41168ad946f81992343e6a",
        "name": "Parent",
        "thumbnail": "<thumbnail_url>",
        "platform": "base",
        "status": "active",
        "created": 1581323914,
        "updated": 1581324021,
        "number_of_components": 1,
        "number_of_text_styles": 0,
        "number_of_colors": 1,
        "number_of_members": 1
    },
    {
        "id": "5e25aca881cd7a431a0d35cd",
        "name": "Linked",
        "thumbnail": "<thumbnail_url>",
        "platform": "base",
        "status": "active",
        "created": 1579527336,
        "updated": 1581324017,
        "number_of_components": 2,
        "number_of_text_styles": 0,
        "number_of_colors": 2,
        "number_of_members": 1,
        "parent": {
            "id": "5e41168ad946f81992343e6a"
        }
    }
]

Now, you can get the colors from each styleguide.

Fetching the colors of related styleguides

curl https://api.zeplin.dev/v1/styleguides/5e41168ad946f81992343e6a/colors?linked_project=:pid -H 'Authorization: Bearer <access_token>'

📘
linked_project query parameter is required in this request because the user may not be authorized to see the styleguide. In that case, linked_project grants the user access to the styleguide

Example response:

[
    {
        "id": "5e4116ccd946f81992343e6d",
        "created": 1581323980,
        "name": "s-parent-cornflower-blue",
        "r": 65,
        "g": 155,
        "b": 249,
        "a": 1
    }
]

curl https://api.zeplin.dev/v1/styleguides/5e25aca881cd7a431a0d35cd/colors?linked_project=:pid -H 'Authorization: Bearer <access_token>'

Example response:

[
    {
        "id": "5e41166d4c30664675ed1bb2",
        "created": 1581323885,
        "name": "s-linked-teflon",
        "r": 85,
        "g": 77,
        "b": 86,
        "a": 1
    },
    {
        "id": "5e41167bd946f81992343e69",
        "created": 1581323899,
        "name": "s-linked-yellow",
        "r": 254,
        "g": 207,
        "b": 51,
        "a": 1
    }
]

Fetching the colors of the project

curl https://api.zeplin.dev/v1/projects/:pid/colors

Example response:

[
    {
        "id": "5e41157cd946f81992343e53",
        "created": 1581323644,
        "name": "p-maroon",
        "r": 87,
        "g": 71,
        "b": 81,
        "a": 1
    },
    {
        "id": "5e411589d75649198ced4eac",
        "created": 1581323657,
        "name": "p-warm-gray",
        "r": 188,
        "g": 181,
        "b": 185,
        "a": 1
    },
    {
        "id": "5e4115974c30664675ed1b94",
        "created": 1581323671,
        "name": "p-whitey",
        "r": 242,
        "g": 242,
        "b": 242,
        "a": 1
    }
]

Following the steps above gets you all the colors that a user can access from a Zeplin project. You can follow the same approach to aggregate other resources such as text styles, components, and spacing tokens.