case studiesAI Contexts· 8 min read

How EGYM Documents a Component Once for People and Agents

EGYM turns Figma specs into Supernova docs and a JSON component contract per component, so designers, developers and coding agents all read the same record.

  • Nezar MansourContent Writer

Share

Summarize

"Hand-written docs drift. Generated docs make things up."

That's how Felix Pfahlert, Design System Lead at EGYM, describes the two options most design system teams have had for documentation. Write it by hand and it's out of date the moment someone changes a variant. Generate it end to end and you get pages that sound authoritative and describe an API that doesn't exist.

Felix's team needed a third option for EGYM One, EGYM's design system. This is how they built it with the Supernova MCP, and what they learned along the way.

Two products, one design system

EGYM has two sides. It builds smart strength-training machines for gyms, and it runs EGYM Wellpass, a corporate fitness benefit that gives employees access to gyms, studios and classes. EGYM One covers both, with one system for web and app and another for machine interfaces.

When the team started documenting EGYM One properly, coding assistants were already part of how the company built product. That changed who the documentation was for.

"There is a new user of documentation in the room nowadays, and that's not a human."

Felix Pfahlert, Design System Lead at EGYM

People read docs to decide: should I use this component, what shouldn't I do with it, is it built in code yet? Agents read docs to build. They need exact names, props and tokens, they can't ask a colleague when they're unsure, and they fill every gap with a confident guess. Docs now had to be clear enough for a person and exact enough for a machine.

Machines extract the facts, people write the judgement

Felix's team split the work by who is better at it. Machines are fast and accurate at counting: how many variants a button has, which states, which sizes, which tokens. People are needed for judgement: when to use a toggle instead of a checkbox, what content guidelines apply, what the accessibility trade-offs are.

EGYM's five-step documentation flow: Figma spec, extract and code, first draft, review loop, component contract

The result is a five-step flow that runs per component:

  1. Figma spec: spec frames describing anatomy, API, tokens and accessibility, built on a customised version of Uber's uSpec.
  2. Extract and code: the Figma Console MCP from Southleft pulls variants, props and token bindings, paired with the code that actually ships.
  3. First draft: Claude Code writes the documentation page into Supernova through the Supernova MCP, always in the same four-tab template (Overview, Usage, Style, Accessibility). Assets are generated in a dedicated Figma file. For general best practice, like how a checkbox or a toggle behaves, the team uses Southleft's Design Systems MCP, which holds data from well-established design systems. That part can be generated with confidence, so people spend their effort on what's specific to EGYM.
  4. Review loop: people comment on the draft in Supernova, and an agent applies the changes.
  5. Component contract: the extracted facts and the human judgement are written into one JSON file per component.

The template took almost 100 rounds

Before rolling anything out, the team tested the flow on the smallest component they had: a link. Felix brought in engineering, design, design systems and product management early, so the template reflected what every group needed from a page.

"We generated almost 100 different templates until we were confident that this was good. And then we started rolling it out."

Felix Pfahlert

Each round was a conversation with the Supernova MCP: comment on the draft, ask for an adjustment, look again. Every component page now opens with where the component is available, direct links to Figma and the coded component, its health, and its related components.

Reviewing in place

The review loop is where Supernova does most of its work for EGYM. Felix comments directly on blocks in the Supernova page, the way a reviewer would on any draft. Then he asks Claude Code to read the comments and fix them.

Slide: reviewed in place. Felix comments on a Supernova documentation block, and the agent replies "Adjusted by AI" in the same thread after rebuilding the figure

Assets come from a separate Figma file on the first pass, and a lot of review comments are about assets that aren't right yet. Those get fixed by hand where needed.

The agent patches the block and the asset, then replies in the same thread with what it changed, prefixed "Adjusted by AI". Only a person resolves the thread. The first pass is the author arguing with the AI. The second is a colleague's review, which at EGYM is always human.

"When I'm working in bulk, I do comment a lot of things and then let it scrape it and do something else in the meantime."

Felix Pfahlert

One file per component

The last step is the one that makes the documentation usable by agents. Every component gets a component.contract.json that answers the questions an agent will ask:

QuestionAnswered by
What variants exist?Figma extraction
When not to use it, and what instead?guidelines.dontUse
Where do design and code disagree?deviations
What is still missing?knownGaps
How far can I trust this?provenance

The guidelines in the component contract come from the reviewed Supernova page. The provenance section records whether a section is still an AI draft or has been reviewed by a person, and when, so an agent (or a developer) can judge how much to trust it. Indexes live in separate files: one for components, one for icons, one for tokens with deliberate descriptions of what each is for. They route agents to the information they need, and let an agent follow the related components when a task doesn't fit.

Slide: one file per component, 131 contracts, 29 authored, every one validated against the schema in CI

At the time of the webinar, EGYM One had 131 component contracts, 29 of them fully authored, and every one is validated against a schema in CI.

The team chose JSON on purpose. Agents follow keys and values more reliably than prose, every tool can read it, and it doesn't lock EGYM into any one AI vendor. The component contracts live in a GitHub repo next to the code, so every change shows up in code review. An internal MCP the team calls One Brain serves them to agents across the company.

"Supernova presents the knowledge to people. The JSON file hands the same knowledge to machines."

EGYM's documentation flow slides

What it unlocked

With the component contracts in place, agents at EGYM build from the system instead of guessing. In the webinar Q&A, Felix showed agents generating repeatable flows from slot-based components, rebuilding screenshots with EGYM One variables, turning a sketch into a login form, and exploring new feature ideas built entirely from existing components and tokens.

Keeping it all in sync is automated too. Scheduled tasks check the Supernova docs and the component contracts for drift, and a warden sub-agent sanity-checks what's actually written down and rescans everything.

The team also built Pulse for Supernova, a Figma widget connected to the Supernova backend. It shows a component's health, links to its code and opens its documentation, which answers the question designers and developers asked Felix most: is this ready, and how do I use it? It's open source: pulse-for-supernova on GitHub.

What Felix would tell another team

Slide: three learnings, three wishes for Supernova
  • Start with one small component: pick something your team uses a lot, describe it in Figma, and get the template right before scaling.
  • Check what the agent says it did: read every write back, including titles, order and content. A success response is not proof. EGYM also runs a warden sub-agent that sanity-checks what's written down.
  • Patch, never replace: comments in Supernova anchor to block IDs, so replacing a whole page orphans them.
  • Verify the pixels: a re-linked Figma frame can return a cached render, so look at the image.
  • Keep facts and judgement in one file: the component contract is where everything the team learned ends up, so nothing lives only in someone's head.

To see the flow running live, watch the Supernova MCP webinar recap. To try the same loop on your own system, connect the Editor MCP or start on the free plan.

Give your agents a system worth following

See how Supernova documents, syncs, and serves your system in one place.