Using AI to create living design system documentation

The Problem With Static Documentation

Every design system starts with good intentions. A Figma library. A Zeroheight page. A SharePoint folder with "the right" assets.

And for a while, it works.

Then a colour changes, or an icon is updated. Slowly, without anyone meaning for it to happen, the documentation drifts. The source of truth becomes a collection of approximate truths.

This is a post about how we focused on documenting only once — and built living documentation for all documentation related to values and assets.

What We Built

We evolved TV 2's design system from a Figma library to also include a GitHub repository. The GitHub repo holds our colours, typography, spacing, icons, logos, flags, and brand assets — all the primitives that make TV 2 look like TV 2.

Our main goal was to update things in one place only.

When colours are defined in a single JSON file, and that JSON file automatically generates both the CSS variables developers use and the visual reference pages designers browse, they can never be out of sync. There is only one file to change. Everything else follows.

How It Works

Imagine a chain.

• A design update is made — e.g. blue.200 is updated
• The change is committed and pushed to GitHub
• Automation starts
• GitHub runs an automated action
• The documentation site reflects the change

That's it. The documentation is always current because it's generated, not written.

Benefits

You never have to ask "is this the latest version?" The documentation page is generated fresh on every change. If it's on the page, it's in the system.

Change a colour in color.json — see the change on the documentation site. Drop a new SVG — it automatically generates a PNG version and lists it on the documentation site.

The Role of AI

The system was built iteratively, with AI as a collaborative partner throughout. But it was not a solo sport.

While the site was built by me as a solo, non-coding designer, it was done in close dialogue with our developers. The goal was to understand how to build a system that would enable them in their work.

AI helped write the scripts that read the JSON files and generate the documentation. It ensured the folder structure was consistent so that icons, logos, and flags could be discovered automatically. It helped set up the GitHub automation that runs everything on every change.

The result is a system that benefits from code — but doesn't require deep coding knowledge. You don't need to know how the pipeline works. You just need to know where to put things.

What's Next

Include design context and design intent for agents. Right now, our component guidelines live in Figma and our design principles in Zeroheight — which makes them unavailable for agents.

* In reality, I update everything twice: once in Figma and once in GitHub. It allows me to serve a better designer experience and a better developer experience at a small cost for DesignOps. Maybe one day it will truly be one place — but I can live with two.