We had documented the design system in Notion, but the same questions kept returning to its maintainers.
A team survey explained why. Some people did not know the documentation existed. Others knew, but left it unopened because their work was already happening in Figma.
The problem was not missing content. It was the distance between the guidance and the decision it was meant to support.
Where did everyone go?
Figma had become the central workspace for our designers. Leaving a component, finding the relevant Notion page, and working out whether it was still current added just enough friction for people to ask a maintainer instead.
That created a loop. Designers could not answer routine questions at the point of use, and system maintainers spent time repeating information the documentation already contained.
Our own survey and support pattern were enough to justify a local change. The answer did not need to be universal. It needed to fit how this team worked.
Documentation by audience
We moved design-facing guidance into Figma, where designers selected and configured components. Each component page showed status, variants, properties, usage guidance, and links to the coded implementation where one existed.
This was not an attempt to make Figma the source of truth for every audience. Storybook remained the better home for coded behaviour and API examples.
The goal was to put each layer of documentation beside the work it governed, then connect the layers clearly.
The anatomy of a component page
For each component, the Figma page answered five questions in order:
1. Can I use it? Status and known limitations. 2. Which version fits? Types and variants. 3. What can I change? Properties and supported combinations. 4. How should it behave? Usage and interaction guidance. 5. Where is the implementation? Links to Storybook and related sources.
The result
After the move, maintainers noticed fewer repeated "where do I find this?" and "which component is current?" questions. Designers could answer more routine questions without leaving the file where they were working.
We did not capture a formal before-and-after count. The result is better described as an observed change: common discovery questions reached maintainers less often.
The trade-off was maintenance across tools. Figma improved discovery for designers, but status and behaviour could drift unless ownership and links stayed current.
The lesson was not "put all documentation in Figma." It was "put guidance at the point of use, define which system owns each fact, and make the path between them obvious."