Why
Documentation is often one of the most tedious parts of building a design system.
Yet it is also one of the most necessary for development to actually use it.
One of the main reasons a design system fails is that it does not get used.
You have to encourage adoption.
What better way to make it easier to use than making it accessible through platforms that do not require an account and that you do not need to learn how to use. Notion meets those premises.
AI gives us the ability to take documentation elsewhere through MCPs.
The MCP (Model Context Protocol) is like the universal USB cable AI uses to connect to many different applications.
The experiment
The design system chosen is a small one called Aegis, with a couple of components and built by hand.
This DS is destined to evolve and grow larger, with components oriented so that AI can use them.
AI has special needs in order to use a component, so you may see things that would not normally apply to a design system.
Foundations
Color, typography, spacing, and other base tokens.
Components
Button with properties for type, state, size, icon-only boolean, among others. Link, simpler, with two variants and their corresponding states.
The skill
A skill is a set of instructions that tells the AI how to do a specific job the same way every time. That way you don’t have to explain it from scratch each time, and the outcome stays more controlled.
In this project, the skill connects where you work (Figma) with where the documentation lives (Notion) through Cursor. You describe in plain language what you want documented; the agent reads Figma, organizes the information, and writes it into Notion pages.
How it works
Each time the skill runs, the agent roughly follows this path:
-
Open Figma
The AI accesses the Figma file.
-
Discover what’s there
Locate variables (the “tokens”: named colors, typography, or spacing) and components.
-
Minimal questions
Language, color format, whether you want a local copy, and so on.
-
Set up Notion
Create the main page, indexes, and sections.
-
Fill with real data
Complete foundations and/or components with data from the file—not invented values.
-
Close and review
Run summary and leave the automatic review ready.
Foundations come from Figma’s variables table: that is the source of truth for tokens.
Components are documented by looking at the live piece (variants, states, bound variables) and, when it exists, an embedded Playground or Showcase view. No screenshots: the goal is a data-backed showcase, not a photo album.
Building the skill
The real process was iterative: ask for too much, get something generic, and narrow it down until the skill respected the real structure of the design system.
I started with foundations only, to lock in the basics: what to ask, how to organize Notion, how to pull tokens without inventing values.
From there came two key adjustments: separate the foundations and components paths because they are not documented the same way, and reduce the intake, which created friction.
The skill moved to inferring scope from the file and asking only what is essential.
On large files it was also necessary to stop re-reading Figma at every step: now it discovers once, saves progress, and fills Notion from that copy.
With stronger rules in place, I tried the skill on a more demanding case: an accordion component from a more mature library.
New failures showed up there, such as ignored documentation, raw colors instead of assigned variables, which finished locking in the skill’s rules.
Those rules require respecting the structure, reading the live component, and documenting only the changes between variants.
The useful part of failing wasn’t fixing a bug, but seeing where AI adds speed and where human judgment is still required.
Those same silent failures we know AI tends to make—a run that is taken as good even when something is missing—were what led to building the hook.
The hook
A hook is a script Cursor runs when the agent finishes a turn.
It was needed because the AI having finished does not always mean the documentation is complete: a page, an embedded view, or a closing step might still be missing.
The hook reads the run summary and writes an easy-to-read message in English: what looks good, what was not completed, and what remains pending for normal reasons.
It only runs when this skill leaves an “armed” close file on finish.
Pros and cons
Pros
- Speeds up a first documentation draft from existing foundations and components.
- Forces written rules that used to live only in the team’s heads.
- Fits a Cursor → human review → Notion workflow.
- The hook closes the loop: it does not only document—it also says what went well and what is missing.
Cons
- Without a well-scoped DS, it invents structure and vocabulary.
- Notion embed and sync still need care around permissions and public URLs.
Result
The experiment’s outcome lives in Notion: foundations, the Button, and process notes.
Overall, the project is not just “export Figma to Notion”: it is a skill + hook system that documents with real data and reviews at the end what was fulfilled and what was not.
Keep in mind that the result you see below is something that can be adapted and changed to the needs of each design system so it delivers the best possible outcome.