Design ↔ Code Inconsistency

Why this is worth solving

Design-code inconsistency is one of the most common sources of friction between designers and developers, and it compounds over time.

A 2px padding difference in a button is not a crisis, but when it exists across thirty components for two years, the codebase no longer reflects the design system and the design system no longer reflects the product. Decisions stop being intentional. Tokens get defined and forgotten. New team members learn the wrong values. What started as a small drift becomes a rebuild.

Solution

I built a reusable workflow using Claude Code, with the figma-cli plug-in instead of Figma MCP which is faster and more token friendly. You can check the repo here: https://github.com/Parnian777/design-audit. The workflow is packaged as a single slash command so anyone on the team can run it in under a minute without needing to understand the underlying tools.

When you run /design-audit, it first asks two questions about scope. On the code side, do you want to audit the whole project, a specific folder, certain files, or just specific lines?

On the Figma side, do you want the whole file, specific pages, or specific frames? This matters because a real project might have a Figma file with twenty pages and a codebase with hundreds of components, and you rarely need to check everything at once. Scoping keeps the audit fast and the output focused.

It then reads the code and fetches the Figma data at the same time, compares them across six categories, and produces three outputs: an HTML report with screenshots from Figma and syntax-highlighted code snippets shown side by side, comments written directly into the source CSS and TSX files at the exact line where each issue lives, and comment pins posted inside the Figma file on the relevant components.

A schematic view of six categories that /design-audit checks

If the Figma file has multiple pages (for example, a Components page and a Layouts page), the tool asks where you want the Figma comments to go, because sometimes the right place to flag an issue is the component definition and sometimes it is the page where that component is actually used in context.

What makes this different from just running a linter

A linter checks syntax rules. This checks semantic alignment between two completely different systems: a visual design tool and a codebase. It resolves Figma variable aliases to their actual hex values, compares those to CSS custom property values, understands that a Figma component instance can diverge from its component definition, and recognizes when a token exists in the design system but has never been wired into any actual CSS rule. None of that is possible with a static analysis tool because it requires understanding both sides of the design-development relationship at the same time.

How it improves the workflow

Before this, catching inconsistencies required a designer to manually open both tools, know what to look for, and spend time writing up findings in a doc or Notion page that developers would then have to cross-reference. The whole loop from "I think something is wrong" to "the fix is in the codebase" could take a day or more.

With this workflow, the same audit takes a few minutes, the findings are already in the Figma file for designers to see, they are already in the code for developers to find with a simple grep, and the HTML report gives both sides a shared visual reference.

Crucially, the workflow is reusable. You can run it before every sprint, after a design system update, or as part of a handoff checklist, and it will always give you a fresh snapshot.

The reusability angle

Because it is a slash command rather than a one-time script, any team member can run it without knowing how the underlying tools work.

It also lives in the project's .claude/commands/ folder, which means it is version-controlled alongside the codebase and improves over time as the team updates it.

This is what I think good AI-assisted tooling looks like: not automating the interesting design decisions, but automating the repetitive verification work so designers and developers can spend their time on the parts that actually require judgment.

Steps Further

This audit was built and tested on a small demo project, both in Figma and in the codebase. The next step is running it on a larger, real-world project to see where it breaks, slows down, or produces noise, and then iterating on the workflow based on what comes up.

More components, more pages, more tokens, and more edge cases will surface problems that a demo file simply cannot.

One practical concern with scaling is cost. Larger codebases and more detailed Figma files mean more tokens processed per run. To make this usable in a professional setting, I prepared a token usage estimation so teams can forecast the cost before committing to a full audit.

This turns it from a tool you run once into something you can plan around and justify to stakeholders.

The scope selection built into the command already addresses part of this. Before the audit runs, it asks you to define exactly which folders or files to check on the code side, and which pages or frames to check on the Figma side. This means you never have to scan your entire codebase or the whole Figma file unless you want to.

You can run a focused audit on a single component, a specific feature folder, or one Figma page in under a minute, and save the full project-wide run for when it actually matters. That balance between depth and speed is what makes the workflow practical for everyday use rather than just a one-time cleanup.