AI Design System Auditor

Building a design system auditor with Claude code and Figma to find inconsistencies across designs

Client

McKesson

< back

AI Design System Auditor

Building a design system auditor with Claude code and Figma to find inconsistencies across designs

Client

Self

< back

TRY DESIGN SYSTEM AUDITOR

Problem

Every design system has gaps. Spacing gets eyeballed, color values get hardcoded, and small inconsistencies accumulate until the UI feels off but no one can point to exactly why. I wanted to see if AI could do the tedious part of the audit so I built a tool where designers stay in control and the model does the checking.

Solution

upload a screenshot and your tokens, and AI flags every violation in seconds.

Setting up with Claude Code

I gave Claude Code a single detailed prompt that defined the full project structure upfront the pages, components, API route, state management, and design direction all in one go.

From that prompt, Claude Code generated the project skeleton: a home screen with a upload zone and a JSON token editor, a results screen that renders sortable issue cards, and a server-side API route that handles the Anthropic API call securely without exposing the key to the browser.

I then added the audit system prompt directly into that API route file, which tells the model to compare an uploaded screenshot against my token values and return a structured JSON list of violations.

Manual Audit

I tested the auditor against GitHub's design system, Primer, because it's one of the few systems with fully public documentation, meaning I could verify the tool's findings against ground truth rather than just eyeballing them.

I ran the auditor on screenshots of GitHub's dashboard, then did a manual inspection of the same screens using Primer's documented token values. For each issue the tool flagged, I cross-referenced it against Primer's spacing scale, color tokens, and type system to check whether the violation was real, a false positive, or an intentional exception the system doesn't document.

I tested the auditor against GitHub’s design system, Primer, because it’s one of the few systems with fully public documentation, meaning I could verify the tool’s findings against ground truth rather than just eyeballing them.

I ran the auditor on screenshots of GitHub’s dashboard, then did a manual inspection of the same screens using Primer’s documented token values. For each issue the tool flagged, I cross-referenced it against Primer’s spacing scale, color tokens, and type system to check whether the violation was real, a false positive, or an intentional exception the system doesn’t document.

Github dashboard

Github primer design system

Figma MCP

Before making any UI updates to the auditor, I asked Claude Code to familiarize itself with the design system, the token names, spacing scale, color values, and component patterns so it had the right context before touching any code.

From there, I made all UX and UI changes directly in Figma first. Once I was happy with the direction, I used the Figma MCP connection to push those designs to Claude Code, which then updated the auditor's codebase to match without me having to manually translate design decisions into written instructions or re-explain the system it already knew.

Before making any UI updates to the auditor, I asked Claude Code to familiarize itself with the design system, the token names, spacing scale, color values, and component patterns so it had the right context before touching any code.

From there, I made all UX and UI changes directly in Figma first. Once I was happy with the direction, I used the Figma MCP connection to push those designs to Claude Code, which then updated the auditor’s codebase to match without me having to manually translate design decisions into written instructions or re-explain the system it already knew.

Before

After

• Added Clear and Reset to default links

Before

After

• Moved category test aligned left for better readability
• Added severity color to border for added scanability

AI Errors

Because AI always makes mistakes here is a list it made during this project:
Put `npm run dev` text inside `.env.local`, breaking the env file

Didn't warn that sharing the API key in chat meant it needed rotating
Used next.config.ts without checking the Next.js version first
Put bg color and layout wrapper in the shared layout instead of each page, requiring a 3-file fix later

Figma mistakes

Built with hardcoded styles instead of the Simple Design System components I asked for
Set layoutSizingHorizontal = "FILL" before appendChild, causing an error
Tried to do too much in one Figma session and hit the rate limit

Sync mistakes

Fetched metadata without get_design_context on the first sync, so it couldn't see actual visual changes
Missed the white background change on the upload screen the first time

Because AI always here is a list of mistakes it made during this project:
Put `npm run dev` text inside `.env.local`, breaking the env file

Didn’t warn that sharing the API key in chat meant it needed rotating
Used next.config.ts without checking the Next.js version first
Put bg color and layout wrapper in the shared layout instead of each page, requiring a 3-file fix later

Figma mistakes

Built with hardcoded styles instead of the Simple Design System components you asked for
Set layoutSizingHorizontal = "FILL" before appendChild, causing an error
Tried to do too much in one Figma session and hit the rate limit

Sync mistakes

Fetched metadata without get_design_context on the first sync, so I couldn’t see actual visual changes
Missed the white background change on the upload screen the first time

Because AI always here is a list of mistakes it made during this project:
Put `npm run dev` text inside `.env.local`, breaking the env file

Didn’t warn that sharing the API key in chat meant it needed rotating
Used next.config.ts without checking the Next.js version first
Put bg color and layout wrapper in the shared layout instead of each page, requiring a 3-file fix later

Figma mistakes

Built with hardcoded styles instead of the Simple Design System components you asked for
Set layoutSizingHorizontal = "FILL" before appendChild, causing an error
Tried to do too much in one Figma session and hit the rate limit

Sync mistakes

Fetched metadata without get_design_context on the first sync, so I couldn’t see actual visual changes
Missed the white background change on the upload screen the first time

TRY DESIGN SYSTEM AUDITOR

Get in touch

erikaweldon@gmail.com

Erika Gensler

Get in touch

erikaweldon@gmail.com

Erika Gensler

Get in touch

erikaweldon@gmail.com

Erika Gensler

< back

< back

< back

< back

Linkedin

TRY DESIGN SYSTEM AUDITOR

Linkedin

TRY DESIGN SYSTEM AUDITOR

Linkedin

TRY DESIGN SYSTEM AUDITOR

Problem

Problem

Solution

Solution

Solution

upload a screenshot and your tokens, and AI flags every violation in seconds.

upload a screenshot and your tokens, and AI flags every violation in seconds.

Setting up with Claude Code

Setting up with Claude Code

I gave Claude Code a single detailed prompt that defined the full project structure upfront the pages, components, API route, state management, and design direction all in one go.

From that prompt, Claude Code generated the project skeleton: a home screen with a upload zone and a JSON token editor, a results screen that renders sortable issue cards, and a server-side API route that handles the Anthropic API call securely without exposing the key to the browser.

I then added the audit system prompt directly into that API route file, which tells the model to compare an uploaded screenshot against my token values and return a structured JSON list of violations.

Manual Audit

Manual Audit

I tested the auditor against GitHub's design system, Primer, because it's one of the few systems with fully public documentation, meaning I could verify the tool's findings against ground truth rather than just eyeballing them.

I tested the auditor against GitHub’s design system, Primer, because it’s one of the few systems with fully public documentation, meaning I could verify the tool’s findings against ground truth rather than just eyeballing them.

Github dashboard

Github primer design system

Figma MCP

Figma MCP

Before making any UI updates to the auditor, I asked Claude Code to familiarize itself with the design system, the token names, spacing scale, color values, and component patterns so it had the right context before touching any code.

Before making any UI updates to the auditor, I asked Claude Code to familiarize itself with the design system, the token names, spacing scale, color values, and component patterns so it had the right context before touching any code.

Before

After

• Added Clear and Reset to default links

• Added Clear and Reset to default links

Before

After

• Moved category test aligned left for better readability• Added severity color to border for added scanability

• Moved category test aligned left for better readability• Added severity color to border for added scanability

AI Errors

Because AI always makes mistakes here is a list it made during this project:Put npm run dev text inside .env.local, breaking the env file

Didn't warn that sharing the API key in chat meant it needed rotating

Used next.config.ts without checking the Next.js version first

Put bg color and layout wrapper in the shared layout instead of each page, requiring a 3-file fix later

Figma mistakes

Built with hardcoded styles instead of the Simple Design System components I asked for

Set layoutSizingHorizontal = "FILL" before appendChild, causing an error

Tried to do too much in one Figma session and hit the rate limit

Sync mistakes

Fetched metadata without get_design_context on the first sync, so it couldn't see actual visual changes

Missed the white background change on the upload screen the first time

Because AI always here is a list of mistakes it made during this project:Put npm run dev text inside .env.local, breaking the env file

Didn’t warn that sharing the API key in chat meant it needed rotating

Used next.config.ts without checking the Next.js version first

Put bg color and layout wrapper in the shared layout instead of each page, requiring a 3-file fix later

Figma mistakes

Built with hardcoded styles instead of the Simple Design System components you asked for

Set layoutSizingHorizontal = "FILL" before appendChild, causing an error

Tried to do too much in one Figma session and hit the rate limit

Sync mistakes

Fetched metadata without get_design_context on the first sync, so I couldn’t see actual visual changes

Missed the white background change on the upload screen the first time

Because AI always here is a list of mistakes it made during this project:Put npm run dev text inside .env.local, breaking the env file

Didn’t warn that sharing the API key in chat meant it needed rotating

Used next.config.ts without checking the Next.js version first

Put bg color and layout wrapper in the shared layout instead of each page, requiring a 3-file fix later

Figma mistakes

Built with hardcoded styles instead of the Simple Design System components you asked for

Set layoutSizingHorizontal = "FILL" before appendChild, causing an error

Tried to do too much in one Figma session and hit the rate limit

Sync mistakes

Fetched metadata without get_design_context on the first sync, so I couldn’t see actual visual changes

Missed the white background change on the upload screen the first time

Linkedin

TRY DESIGN SYSTEM AUDITOR

Linkedin

TRY DESIGN SYSTEM AUDITOR

Linkedin

TRY DESIGN SYSTEM AUDITOR

• Moved category test aligned left for better readability
• Added severity color to border for added scanability

• Moved category test aligned left for better readability
• Added severity color to border for added scanability

Because AI always makes mistakes here is a list it made during this project:
Put `npm run dev` text inside `.env.local`, breaking the env file

Used `next.config.ts` without checking the Next.js version first

Set `layoutSizingHorizontal = "FILL"` before `appendChild`, causing an error

Fetched metadata without `get_design_context` on the first sync, so it couldn't see actual visual changes

Because AI always here is a list of mistakes it made during this project:
Put `npm run dev` text inside `.env.local`, breaking the env file

Used `next.config.ts` without checking the Next.js version first

Set `layoutSizingHorizontal = "FILL"` before `appendChild`, causing an error

Fetched metadata without `get_design_context` on the first sync, so I couldn’t see actual visual changes

Because AI always here is a list of mistakes it made during this project:
Put `npm run dev` text inside `.env.local`, breaking the env file

Used `next.config.ts` without checking the Next.js version first

Set `layoutSizingHorizontal = "FILL"` before `appendChild`, causing an error

Fetched metadata without `get_design_context` on the first sync, so I couldn’t see actual visual changes