Why should I use Notion to document my design system?

You should use the tools that work best for your team. Many of the best product teams in the world are using Notion as a knowledge base for their organization.

It was a no-brainer for us to choose Notion as a new Destination for Specify to help you automatically:

  • Document your brand guidelines in Notion

  • Create public pages for press and brand kits

  • Automate the maintenance of your design system documentation

Where your design data is coming from

The design tokens and assets you'll be distributing to Notion must be collected from Sources beforehand (e.g., Figma).

👉 Learn more about how to add Figma as a Source

How to add Notion as a destination

  1. Add Notion in Specify

    • Go to your Specify repository your want to extract design data from

    • Go to Destinations and click on Add destination

    • Select Notion as your destination in the first step

  2. Connect your Notion account

    • Select your Notion workspace by clicking on Connect workspace

    • Choose which pages you want to give Specify access to

  3. Select the token type you want to synchronize (only colors, vectors, and bitmaps are supported for now)

  4. Choose if you want to duplicate our design system documentation Notion template or continue without it

    Check how to use our Notion template in this other article.

  5. Choose if you want to sync your design data in an existing database (e.g. using a template) or create a new one from scratch

  6. Give the link of your existing Notion database OR the link of the Notion page you want your design data to be distributed to

  7. Validate it and see your design data distributed inside a Notion database on your Notion page 🎉

    Due to Notion API's limitations, your first synchronization might take several minutes.

    You should then see a new database created by Specify with your design data if you choose to create one from scratch (here I chose to distribute colors).

Do's and don'ts

🚫 Don't edit existing database columns created by Specify

All columns and values created by Specify will automatically be overridden by Specify following each synchronization between Specify and your Notion pages.

🚫 Don't edit values in the SpecifyId column

Updating values in the SpecifyId column will break the synchronization between Specify and your Notion document. We recommend you hide this column in your view.

✅ You can add and edit custom columns in the generated database

You mustn't update existing columns and values created by Specify but you're free to add any custom column to the generated database. Specify will ignore them and they will remain as is after each synchronization.

Go further by creating linked databases

You can create linked databases on other pages that will call the original database created by Specify. They will always be in sync!

For example, you can start with a Brand Guidelines Notion page and insert a linked database referring to the database Specify generated. That way, you can choose the display (like a gallery) or filter you’d like to describe and document those colors.

👉 Learn more about linked databases in Notion

Did this answer your question?