Rebuilding Grafana's Design System as an AI-Ready Foundation

Primary Goals

My Process

Assessing the Current State

When I started on Grafana's marketing website, AI-accelerated development had produced a sprawl of duplicated components with no shared styles or functionality. Design and engineering weren't short on goodwill; they were working from different sources of truth. Of the 328 token entries in Figma, 19% had overlapping values and 21% were missing or wrong in code, so roughly one in five design decisions wouldn't match what shipped.

Before tackling components, I needed to build a token foundation both teams could rely on.

Building a Primitive Layer

First, I cleared the noise in Figma: removing unused values, consolidating duplicates, and using AI to migrate hundreds of color references. Color primitives dropped from 257 to 137, so designers had one neutral ramp instead of five. I then added primitives that existed in code but not Figma, and aligned the spacing, radius, and typography scales to code. Code was the right source to align to: earlier cleanup had given it the clearer foundation, and feature work was ongoing, so code changes had to stay non-breaking. The result was 203 unique primitives, with every existing reference remapped to them.

I also wrote a skill and scripts to export tokens from Figma as W3C Design Token JSON and convert them into CSS variables for the Tailwind theme. That let me remove the last duplicated color ramps from the codebase and document the primitives in Storybook, the first step toward making Storybook the system's source of truth.

Primitive color tokens documented in Storybook.

Adding Meaning with Semantic and Component Tokens

Primitives describe what a value is; semantic tokens describe how it's used. I created 156 semantic tokens covering spacing, corners, borders, forms, typography, and color, building in contrast compliance, light/dark theming, and a consistent type hierarchy.

Semantic tokens do most of the work, so designers and engineers rarely reach for primitives. Fewer decision points leave fewer places for drift.

Semantic text tokens documented in Storybook.
Semantic border tokens documented in Storybook.

For components like buttons that don't map cleanly to semantic tokens, I added a minimal component layer, with guidance on when a token belongs there. Rolling both layers out in Figma took 2,800+ non-breaking changes without disrupting in-progress work. The codebase followed during component renovations.

Component button tokens documented in Storybook.

Auditing Components and Creating a Roadmap

Next, I audited Figma and the codebase for components missing from one side or mismatched between them. I turned the findings into a task list with effort estimates, noting whether each fix belonged in Figma, code, or both. The roadmap gave stakeholders visibility into progress and gave agents clear direction.

Renovating Components

Each component was aligned to the new tokens and its coded counterpart, added to Storybook, documented in a guideline.md, tested, and shipped to production. Outdated components were removed or replaced along the way. To refactor production components safely, I set up visual regression testing in CI/CD across the system and its consuming apps, catching unintended changes before launch.

BEFORE - Tabs component in Figma prior to renovation with multiple versions of the same component mismatched from code.
BEFORE - Tabs component in Figma prior to renovation with multiple versions of the same component mismatched from code.
AFTER - Renovated Tabs component in Figma matching code and clearly documented.
AFTER - Renovated Tabs component in Figma matching code and clearly documented.
AFTER - Renovated Tabs component in Storybook, with properties and variations clearly documented and accessible via the Storybook MCP.
AFTER - Renovated Tabs component in Storybook, with properties and variations clearly documented and accessible via the Storybook MCP.

Keeping It Synchronized

Synchronization only matters if it lasts, so I built guardrails into everyday workflows.

Guidelines for people and agents. I documented clear rules for token and component management through skill and guideline files, so the same source of context was available to designers, engineers, and AI agents alike.

Token linting. Linting flags out-of-compliance tokens where they occur, so migration happens during normal development instead of as a separate project.

Design token proposals in real environments. Designers propose token changes through a custom Figma plugin I created that triggers a GitHub Actions workflow and opens a PR with the changes. Design and engineering review and approve them together in a real staging environment instead of static mock-ups.

Storybook as the Source of Truth

Designers also need current versions of complex components built from the core system, but hand-maintaining a Figma copy of Storybook's full library is costly. I built a skill that uses the Storybook MCP to generate those components in Figma from the latest Storybook definitions. Nobody has to rebuild them by hand, and Storybook has become the design team's source of truth for production components.

Component generated in Figma using a skill created for the design team to pull from the Storybook MCP. Layers named correctly, properties matching, and override locations labeled - e.g. background image.
Component generated in Figma using a skill created for the design team to pull from the Storybook MCP. Layers named correctly, properties matching, and override locations labeled - e.g. background image.

Better Inputs, Better Agent Output

With new designs built from the core library and system standards, agents work from comprehensive guidelines and well-structured Figma files. That cut feature development time by 68% and earned praise from both teams.

What I Learned

Clear foundations can feel like a slowdown to teams who want to move fast, but AI makes them more important than ever. Here, the missing structure was the root of the collaboration struggles. A shared structure sped up feature work and improved morale on both teams.

With the roadmap and foundations in place, I renovated, documented, and shipped 30+ production-quality components in Figma and code in under a month without breaking production or design workflows. That wouldn't have been possible before agentic engineering.