Echo Docs - Streamlining design system documentation to align teams and ship faster

Echo is Typeform's design system. It supports both the Creator Experience (CX) and Respondent Experience (RX), and runs under a collaborative model governed by a pretty lean core team of four. When I joined, Echo already had solid adoption (every team builds with Echo UI) and good sync between Figma and code through token exports.

The problem wasn't adoption, it was scaling. Docs were scattered across Figma frames, Storybook and Notion. Our half-yearly Echo Survey kept surfacing the same feedback from consumers: "More component and pattern examples of how to implement Echo properly."

Leadership wanted to open up Echo documentation so designers, engineers, content and motion folks could all contribute, but without things getting messy or inconsistent.

A docs site felt like the right call, but there was some baggage. A previous MVP had been attempted and abandoned. It was hosted on GitHub and written in Markdown, so only people with technical knowledge and GH access could update it.

I needed to make the case that this time would be different. Scaleability and ease of access had to be the number one requirement. We looked at a few out-of-the-box solutions but none of them felt quite right for where we wanted to take things.

We landed on Notion paired with Docusaurus. With a bit of engineering work, we built a pipeline to convert Notion pages into MDX for the docs site to consume. Our engineer Fernando wrote a great blog post about the architecture if you want to dig into the technical details. Notion made sense for a few reasons:

• Typeform already uses Notion a lot as a company, so the barrier to contribution was really low
• The Notion API is powerful enough to programmatically pull content
• It keeps our Echo MCP server fed with always up-to-date context from our latest guidelines
• Notion AI lets consumers query docs directly, which takes some of the support load off us as a core team

Because docs were so spread out, we couldn't just migrate everything and hope people would find it. We kicked off with a tree test, benchmarked against other design system docs, and tested the new layout with 10 engineers and 10 designers. Refined and optimised based on their feedback and input from leadership.

We also had to think about sections beyond just components and patterns. AI, accessibility guidelines, motion and content all needed a home.

On the technical side, we mapped Notion blocks to web elements so the output looks consistent regardless of who's writing the documentation.

With contributors coming from content design, motion, engineering and product design, we needed everyone writing docs in the same way. We put together guidelines covering structure, tone and formatting so Echo docs read consistently no matter who wrote them.

One of the main things we did to address the "more examples" feedback was embedding a live code editor directly into component pages. It imports Echo components so both designers and engineers can play around with configurations and pre-built examples right in the browser.

During a company hackathon, we took this further and built a dedicated Echo Sandbox with live code updates, shareable links, RTL testing and pre-built examples. The shareable links turned out to be the thing people got most excited about. Everyone loved being able to send each other working Echo layouts.

Notion API rate limits
Part way through, we started hitting Notion's API rate limits on every build. We had to re-architect the update process. Docs are now updated via an automated cron job on Monday mornings.

Notion block styling
Getting Notion blocks to look half decent on the web was harder than expected, especially spacing and columned layouts. We also learned pretty quickly that Notion Databases were way more powerful than plain pages for structured content (metadata, structured fields etc.)

Brand alignment
The original goal was for Typeform.design to be the whole home of design at Typeform. After conversations with the brand team, we decided to keep things separate. Their documentation was already in place and the complexity of merging it wasn't worth it yet. Might still happen in future though!

Launching is one thing, getting people to use it is another. We set up monthly office hours, release announcements and weekly Friday updates. We also encouraged teams to review and contribute to documentation. On the analytics side we set up Datadog with session replays. The site hit over 2,000 visits within a few months of going live.

From engineers

"As with all things, I was reluctant at first. I'm very used to Storybook, so I didn't understand the need for extra docs. After seeing the new docs, though, I have to say that they're very well curated."

"Super useful! I can see that this will be the SoT in the future for both PDs and Engs."

From designers

"Very glad we'll have things documented in this way and also that we can edit/update without relying on engineers."

"Very clean design and well organized information architecture. I really appreciate how accessible it has been made for everyone to edit its content through Notion."

• Content migration - The site is up, but it needs content! Migrating, updating and adding docs for all aspects of the system is ongoing. Big focus on accessibility, AI guidelines and motion.
• Echo Sandbox - The sandbox has seen the most engagement, especially shareable links. We've already got a bunch of requests to bring AI features into it, combining it with our MCP server.
• RX integration - We're only supporting CX Echo docs at the moment. RX recently did a large refactor and we're looking to bring it under the same umbrella.