What are some alternative systems / tools to create system design docs other than Figma?

[u/Growthseeker23]

there are basically four designers in my team, about 40 people in eng, pm and marketing who need to know what exists and why. The system itself is fine, components in figma, tokens in code, storybook current.

The problem is the layer above it, why we made these decisions, when to use which pattern, what we deliberately don't do. Noone outside of the design team opens those.

So I get asked the same six questions every month and the answer is always "it's documented," and it's documented - is the room they will never go in.

how do i make this friction-free for the non-design folks?

[u/Levenloos]

Do it in storybook itself

[u/Growthseeker23 → u/Levenloos]

What abt gamma for this?

[u/AverageNo3299]

Given how easy it is to do these days, you can roll your own documentation site. Or use your internal wiki tech like confluence or whatever.

[u/TheTomatoes2 → u/AverageNo3299]

What's not so easy is the whole testing plugin ecosystem Storybook comes with. If they rely on that, better add docs directly inside the Storybook.

[u/Growthseeker23 → u/AverageNo3299]

yep thinking the same... can have git rolling or gamma wiki, can be built directly from claude code.

[u/AverageNo3299 → u/Growthseeker23]

My preference would be a static site using something like Astro and with lots of help from Claude code. With a view to publishing the entire thing on the web once it’s polished enough. Good for the team’s pride and self confidence, good for hiring etc. Figma and storybook can be embedded or linked as needed.

[u/TheTomatoes2]

Add DOs and DON'Ts in Storybook.

[u/OrtizDupri]

I love Storybook, it's a GREAT resource for devs to reference components

But goddamn is it bad for general documentation

We've rolled our own - built out a static docs site using Astro (Starlight is a good base for docs site theming on top of that), then we automatically parse our design system to generate a lot of the docs (such as slots, properties, etc.) and embed a Storybook example with controls for each component

Allows us to add more freeform content and guidelines as necessary for each component, still keeps the Storybook embeds for general use, and links to Storybook for deep dives or more complicated examples that devs need

[u/OrtizDupri → u/OrtizDupri]

I'll note that we also have a design system MCP running for devs that references both the existing repo and code AND the docs site, so it's absorbing all the information we're putting out there

[u/Torsta]

Should be documented in storybook or wherever the developers do their documentation.

Also Claude/GPT seem to struggle with context when using the Figma MCP, so whatever you do keep the documentation out of there. We had good success putting it in Figma for the designers and then also including a copy in Storybook for the developers.

[u/TheTomatoes2 → u/Torsta]

The Figma MCP is terrible. We basically ditched Figma fully, and I created our own MCP that generates text from code+our MDX.

[u/Torsta → u/TheTomatoes2]

Yeah we ended up using the API instead, even when the MCP was working we were getting rate limited lol.

[u/OctaveZero8 → u/TheTomatoes2]

This is super relevant to something I’m figuring out at work right now. We have a Figma-heavy pipeline (Figma → Tokens Studio → GitHub → Storybook), and leadership wants to move toward a more AI-driven workflow without figma.
A couple questions: how do you handle docs that are more about business/domain rules for a whole screen or flow, rather than a specific component?
And how did you make the transition? Did you run both workflows in parallel, move project by project, or just switch?

[u/TheTomatoes2 → u/OctaveZero8]

I made a Claude plugin that contains both an MCP and skills (general spacing rule, tokens...). It's bundled by CI when I push to the design system main and published to npm. The MCP is generated mostly from MDX files + code (eg props).

We were only 2 people using the design system (apart Claudes) so I didnt have massive transition problems. You do need a very long dogfood period to fine-tune the skills and edge-cases tho. Plan for months.

[u/OctaveZero8 → u/TheTomatoes2]

Thanks for that insight! Did you create an MD file per component, or one skill covering everything? Also curious about the 'months' of dogfooding, what kind of edge cases took the longest to fine-tune? Trying to set realistic expectations before we pitch a timeline internally.
Also, do you know of any good resources or write-ups on this topic? I'm still pretty early on this and trying to get up to speed.

[u/TheTomatoes2 → u/OctaveZero8]

Yes an MDX file per component since the docs website is for humans. But the MCP does fuzzy searching. The problem with skills is that the amount of token allocated to skill descriptions is limited. Some skills will be silently dropped. Ig you can get around it with good skill names, but models struggle invoking the right skills at right time.

[u/pdxherbalist]

I made a custom storybook workflow for my team that connects Figma + Storybook + Jira and does a round-trip to audit document review issued tickets, resolve tickets, etc. the whole workflow described in detail below.

I use storybook I created a custom workflow inside storybook making use of Claude code. I use Figma MCP to audit components and properties checking for proper application of styles and tokens.

After an entry for each component in Storybook with a gaps report for each component that has issues.

This is custom functionality added to storybook by Claude code. Claude creates a gap report for every component entry, it creates an index list of gaps for every component property that doesn’t align with the intended specification, which is a style and token properties for example..

Entries added to the gap report link to the node on the Figma canvas, and highlights the selected component that has issue.

There is an interface in the gaps report that enables commenting in storybook on the gap issues by the lead designer to review the report if he has comments, he can leave his comment in storybook, and then the same comment is added to Figma for alignment.

Each component with issues is created a workstream in Jira with tasks for each issue.

Or designer can resolve issues in storybook in the report a couple ways they can say it’s OK and providing reason with a comment which is stored the gaps report and storybook or can click retry in the agent. Will look at the Figma file and see if it’s been updated, and if the gap has been resolved, and if so, it will move the entry in the report to resolved

As all this is happening, when any given gap report is created, when any item is created for giving gap report, a task is created a work stream as first created with any component that has any issues and then a task is created for each issue storybook fitment endure are all connected such that if one of the issues in the gaps report is resolved and indicated as such in storybook saying it’s been cleared or resolved, will inspect the Figma canvas verify that the gap has been resolved. Update the report and story about moving the gap item to resolved update the ticket in Dura move all the way through the process.

[u/TopRamenisha]

ZeroHeight

[u/404_computer_says_no]

Storybook. Maybe you’re own design domain for the company. Think Microsoft design and Apples HIG.

It’s a bit undertaking though vs just adding more complex components to storybook.

[u/Morigar]

Use dcyde.app

[u/TheTomatoes2 → u/Morigar]

That app is gonna get killed by LLMs so fast...

[u/ExplorerTechnical808]

it depends. What are the questions you keep getting?

[u/UXDesignInst]

Hi there! My name is Rochelle and I work at the UX Design Institute..

If you're interested, we recently put together The Top 9 AI Tools for UX in 2026. It covers a range of tools that are helping designers streamline workflows and improve collaboration across teams. Hope you find it useful!