Documentation

Introduction

Design System Auditor is an automated testing and verification tool that bridges the gap between Figma design tokens and live CSS implementations. It evaluates the health of your frontend by autonomously rendering any public website, web app, or staging environment, and mathematically calculating design drift against your source-of-truth tokens.

Who is this for?

• Designers: Prove where implementation drifts from the design system without manually inspecting browser developer tools.
• Engineers: Receive actionable bug tickets that provide the exact CSS variable/token needed to fix a styling issue, rather than vague "this looks wrong" feedback.
• Design System Managers: Track overall health scores, audit massive token collections across hundreds of URLs, and monitor compliance trends over time.

Getting Started

The auditor requires no installation in your local code repository (no SDKs, no NPM packages, and no CI/CD pipeline modifications). It operates entirely via our Figma Plugin and Web Dashboard.

1. Install the Design System Auditor plugin from the Figma Community.
2. Open the plugin in a file that contains your design system variables or Tokens Studio data.
3. Enter a target URL and select a Figma frame (to dictate the viewport size).
4. Click Run Audits.

Tiers & Paid Plans

You can generate as many Free Tokens as you like directly from our website's pricing page to continue casual testing. However, if you are working on a large application, you can upgrade to a Pro or Business license to unlock advanced capabilities like Authentication, Bulk Subpage Auditing, Custom Themes, and longer data retention.

The Figma Plugin

The plugin serves as the command center for the auditor engine. When you trigger an audit, the plugin securely extracts your design tokens, packages them with your chosen settings, and dispatches them to our edge network infrastructure.

Supported Token Formats

The plugin automatically detects and standardizes your design tokens. Zero manual mapping is required. It currently supports two primary architectures:

1. Figma Native Variables

The plugin automatically reads your local variable collections via the Figma API, resolving colors, numbers (spacing, radii), and string values. It also tracks the associated Light/Dark modes defined in your collections so the auditor can verify specific themes.

2. Tokens Studio (W3C Format)

If you use the popular Tokens Studio plugin, we natively parse the W3C JSON payload attached to your Figma document. This includes full support for resolving mathematical aliases, typography composites, and shadow composites.

Figma Frames vs. Custom Frames

The auditor web browser needs to know what dimensions to render your website at. By default, you can select any top-level frame in your Figma document. The auditor will automatically detect its dimensions (e.g., an iPhone 14 frame at 390x844) and instruct the headless browser to emulate that exact device profile.

Custom Frames: If you are auditing a site but don't have a specific Figma mockup to reference, click the "Add Custom Frame" button in the plugin. This allows you to manually input a Width and Height (e.g., 1920 x 1080) to force the auditor web browser viewport to a specific breakpoint.

Using the Dashboard

Once an audit completes, click "View Audits" in the plugin to open your secure web dashboard. The dashboard processes the raw data and visualizes the discrepancies.

Navigation & Health Metrics

At the top of the dashboard, you will find controls to navigate your data and track your design system's implementation quality over time.

• URL Menu: Switch between different webpages or web apps you have audited.
• Frame Menu: Select the specific viewport or device profile (e.g., Desktop, iPhone) to view results for the current URL.
• Audit History: Browse past audits for the selected URL and Frame combination. This menu displays the exact timestamp and the theme (Light/Dark) used for the run, allowing you to easily compare historical changes.
• Health Score: An aggregate percentage grade representing how closely the computed CSS matches your design tokens. Rogue and Near-Miss values proportionally reduce this score.
• Health Trendline: A visual graph plotting your Health Score across all past audits, making it easy to see if design debt is being resolved or if it is accumulating over time.

Actionable Debt Table

We do not just tell you that a color or pixel value is wrong; we calculate how wrong it is, and then suggest the closest matching token from your system.

• Pass (Green): The computed CSS matches a token perfectly within acceptable browser rendering margins.
• Near-Miss (Yellow): The developer hardcoded a value (e.g., #3B82F5) that is mathematically nearly identical to a system token (e.g., var(--color-blue-500)). The suggested token is provided so they can swap it out.
• Rogue (Red): A value was found that has no mathematical equivalent anywhere in your design system. This usually indicates a completely custom, unapproved style that requires manual design review.

Filtering & Grouping

When auditing large pages, you may generate thousands of violations. The dashboard is built to handle massive payloads smoothly.

• Group By: Use the "Group By" dropdown to cluster violations. Grouping by Category separates Typography from Spacing and Colors. Grouping by Element (e.g., button.primary) allows an engineer to fix a single CSS class and resolve dozens of violations simultaneously.
• Search: The search bar instantly filters the table. Searching for a specific hex code, class name, or token alias will instantly isolate those rows.

The Visual Heatmap

Click "Visual Heatmap" to open the interactive drawer. The auditor engine captures a high-fidelity screenshot of the rendered page and plots the design debt directly onto it.

Interactive Dots: Red (Rogue) and Yellow (Near-Miss) dots pulse over the offending DOM nodes. Hovering over a dot will highlight its corresponding row in the data table and display a tooltip with the exact CSS property that failed.

Figma Overlay Mode: If you selected a specific Figma frame (rather than a Custom Frame) when launching the audit, the heatmap drawer will overlay your raw Figma design directly on top of the live screenshot. Use the Split slider or the Opacity slider to swipe back and forth, allowing you to instantly spot subtle layout shifts or margin discrepancies.

Advanced Guides

Authentication (Private Sites)

Available on Pro and Business plans. If your target app or staging environment is protected by a login screen, toggle "Authentication Required" in the plugin.

Provide test credentials (username and password). Our heuristic engine will automatically locate the login inputs, bypass the gate, and audit the protected routes behind the login. We do not store these credentials; they are held in memory just long enough to authenticate and are destroyed immediately.

Link Harvesting (Bulk Auditing)

Available on Pro and Business plans. Toggle "Audit linked subpages" in the plugin before running.

The auditor will securely load the target URL, discover all internal links belonging to the same origin, and concurrently dispatch background workers to audit those subpages using the exact same device profile and theme. This is the fastest way to audit an entire component library or documentation site in seconds.

Auditing Localhost Sites

Because the auditor engine runs securely on Cloudflare's global edge network, it cannot directly access URLs like http://localhost:3000 running on your private machine.

To audit a local development server, you must temporarily expose it via a secure tunnel. We recommend using one of the following free tools:

• VS Code Port Forwarding: If you use VS Code, open the "Ports" tab in the terminal panel, click "Forward a Port", and enter your local port (e.g., 3000). Change the visibility to "Public" and copy the provided URL.
• Ngrok: Run ngrok http 3000 in your terminal. Ngrok will provide a public URL (e.g., https://1234-abcd.ngrok-free.app).
• Localtunnel: Run npx localtunnel --port 3000 in your terminal.

Paste the generated public URL into the Figma plugin to run your audit.

Troubleshooting & Edge Cases

Why are dots missing from the heatmap?

To preserve browser memory and visual accuracy, the auditor captures a fixed-viewport screenshot (e.g., 1440x900) rather than a full-page scrolling screenshot. If a violation occurs on an element far down the page (below the fold), the dot will not be drawn on the heatmap because it exists outside the boundaries of the image. However, the violation will still be recorded and visible in the Actionable Debt Table.

Why are my web fonts failing the audit?

If your Figma tokens specify a custom font (e.g., `Circular Std`), but the developer has not actually loaded that font file on the target website, the browser will fall back to a system font. The auditor reads computed browser values, so it will flag this as a font mismatch. Ensure your target site is properly loading all required font assets.

Does the auditor support Canvas or WebGL?

No. The auditor evaluates the DOM (Document Object Model) and computed CSS styles. Elements rendered inside a <canvas> tag (like WebGL games or Three.js scenes) do not expose their internal styling to the DOM and cannot be audited.

Frequently Asked Questions

Does it support Dark Mode?

Yes. The auditor automatically detects the native theme associated with your Figma frame by reading the explicit variable modes. You can also manually override this in the plugin settings (Pro/Business feature) to force the auditor web browser viewport to emulate a prefers-color-scheme: dark profile.

How does it handle CSS animations?

The auditor evaluates motion tokens by extracting computed transition-duration and transition-timing-function CSS properties to ensure your developers are using your system's standardized motion curves (e.g., var(--motion-fast)).

Can I share an audit with my developers?

Yes. In the dashboard, click the "Share" button in the top right. It generates a secure, read-only link containing the visual heatmap and the data table that you can paste directly into Jira, Linear, or Slack.

Security & Privacy Policy

Data Retention & Cloudflare KV

All data generated by an audit (screenshots, visual heatmaps, and JSON payloads) is stored securely on Cloudflare's edge KV network and is strictly bound by an automated Time-To-Live (TTL) expiration. Once the TTL expires, the data is permanently wiped from the servers.

• Free Tier: Data is permanently wiped after 7 days to match the token lifecycle.
• Pro Tier: Data is permanently wiped after 90 days.
• Business & Lifetime Tiers: Data is permanently wiped after 180 days (or 90 days for Lifetime).

Infrastructure Security

The auditing engine runs on isolated, ephemeral Cloudflare infrastructure. The headless browser instances are destroyed immediately after the crawl completes. If you provide login credentials for staging authentication, they are never written to disk or saved to our database.

No Source Code Scraping

The auditor does not download or store your React, Vue, or HTML source files. It only extracts computed CSS values directly from the browser's rendering engine.