Skip to main content
This page covers common problems organized by type. For integration-specific problems, also see the troubleshooting sections on the Tokens Studio and GitHub pages.

​
Plugin problems

A blank screen usually means the plugin UI failed to load. Try these steps in order:
  1. Close and reopen the plugin. Right-click the canvas, select Plugins > LintKit, and reopen it. This forces the UI to reload.
  2. Check for Figma updates. An outdated version of Figma can cause plugin rendering failures. Go to Figma menu > Check for updates and install any available updates.
  3. Disable other plugins. In rare cases, another plugin running simultaneously can interfere with LintKit’s UI. Close all other plugins and reopen LintKit.
  4. Reinstall the plugin. If the problem persists, uninstall LintKit from the Figma Community page and reinstall it. Your settings are stored per user and persist through a reinstall.
LintKit processes nodes in batches to avoid freezing Figma, but files with thousands of nodes can still cause slowdowns:
  1. Scan a selection instead of the full page. Select a specific frame or section on the canvas before opening LintKit. This is much faster than scanning the full page.
  2. Close unused pages. Figma can be slower with many pages loaded, even though LintKit only scans the current page.
  3. Close and reopen if unresponsive. If the plugin becomes completely stuck, close it and reopen. Scan a smaller scope.
Selection scan is the fastest way to use LintKit on large files. Select the frames you care about and let LintKit scan just those.
Scan time scales with the number of nodes in the current scope. A page with a few hundred nodes scans in under a second. A page with tens of thousands of nodes may take several seconds.This is expected. Some rules (like Orphaned Fills with library matching) involve additional work per node.To speed things up:
  • Use selection scan. Select specific frames instead of the entire page.
  • Disable unused rules. Each enabled rule adds to scan time. Turn off rules you’re not actively using in Settings.
  • Close other plugins. Other plugins compete for Figma’s processing time.

​
Library and style problems

LintKit only treats external libraries as active when you explicitly add them. If a library isn’t showing up:
  1. Make sure the library is registered. Libraries must be added by URL in the Sources panel, or by running LintKit inside the library file. Using a component from a library in your working file is not enough to register it.
  2. Check your network connection. Library features require network access. When offline, only cached registered libraries are available, but core scanning still works.
  3. Check your Figma Personal Access Token. Library-aware features (Smart Replace, adding libraries by URL) require a PAT with the correct scopes. Go to Settings and verify a token is connected. Your token needs all four scopes:
    • file_content:read
    • file_metadata:read
    • library_content:read
    • library_assets:read
    Figma doesn’t allow editing scopes on an existing token — if a scope is missing, create a new token with all four. See Quickstart — Connect your Figma token for setup instructions.
  4. Check if the library was removed. Removing a library fully purges it — it won’t reappear until you add it again explicitly.
When LintKit flags an orphaned fill or stroke, it suggests the nearest matching style from your libraries. If no suggestions appear:
  1. No libraries registered. You need at least one library added in the Sources panel (by URL or by running LintKit inside the library file). LintKit also needs network access to read library styles.
  2. No close matches exist. LintKit only suggests styles within your configured colorTolerance (default: 5 Delta E). If no library style is close enough, no suggestion appears. Raise the tolerance in Settings to see broader suggestions.
  3. The file has no library styles. If you haven’t registered any libraries, there are no styles to suggest.
  4. Smart Replace needs a connected token. Cross-library style matching requires a Figma Personal Access Token. Without one, Smart Replace only matches against styles already in the current file. Add a token in Settings or during first-run setup.
This happens when a library file has components that aren’t formally published through Figma’s library publishing flow. Common causes:
  • Duplicated or forked Community files. When you duplicate a Figma Community file, publication status is not preserved. The file contains components, but Figma doesn’t treat them as published library components.
  • Styles published without components. The library author may have published color and text styles but not toggled components on for publishing.
How to publish components:
  1. Open the library file in Figma (you need edit access).
  2. Open the Assets panel in the left sidebar, or go to File menu → Publish styles and components.
  3. In the publish dialog, toggle on the components you want to make available.
  4. Click Publish changes.
After publishing, close and reopen LintKit in your working file. The library should now show a component count, and components will appear in the Replace Component dropdown.Alternative — add the library by URL:If you don’t have edit access to publish components, you can still add the library by pasting its Figma file URL in the Sources panel. LintKit will pull in the library’s published styles and components for matching.
This is a Figma platform behavior, not a LintKit limitation. Figma’s REST API only exposes components that have been formally published as library assets.
See the dedicated Tokens Studio troubleshooting section, which covers:
  • API key rejection
  • No rules auto-configured after sync
  • Stale tokens
  • Network errors
  • Variable disconnection after renaming tokens
  • Theme switching not working
  • Designers seeing different token versions
See the dedicated GitHub troubleshooting section, which covers:
  • Authentication errors (401/403)
  • File not found (404)
  • Token format not detected
  • Network timeouts
  • Tokens lost after team member pushed

​
Finding problems

Free users get 5 one-click fixes per session. When you see this message, you’ve used all 5 for the current session.Upgrade prompt showing the free fix limit has been reached
  • Close and reopen the plugin to reset the counter and get 5 more fixes.
  • Upgrade to Pro for unlimited fixes. See pricing.
The limit applies to one-click fixes only. You can always fix findings manually by editing layers on the canvas — the limit doesn’t prevent you from making changes yourself.
Four rules only produce findings when scanning a published library file:
  • Unused Styles — finds styles not used on the current page
  • Hidden Components — finds components hidden from publishing
  • Missing Descriptions — finds components and styles without descriptions
  • Variable Completeness — checks variables for missing mode values, broken aliases, and missing descriptions
These rules are silent in regular design files. This is intentional — they check library health, which only applies to files that publish components and styles.
LintKit skips layers inside component instances. Layers inside an instance are controlled by the main component — editing them would create overrides rather than fixing the root cause.To fix findings that originate from a component, navigate to the main component and fix them there. Changes propagate to all instances automatically.
LintKit skips layers with mixed values because it can’t determine the intended value:
  • Mixed corner radii — each corner has a different radius
  • Mixed fonts — a text layer contains multiple font families or sizes
  • Mixed stroke weights — stroke weights differ across sides
To fix, select the layer and make the values consistent, then re-scan.
LintKit excludes elements rotated more than 0.1 degrees from fractional pixel checks and some spacing checks. Rotation legitimately produces fractional values — a rectangle at a 15-degree angle has sub-pixel coordinates even if it was placed on a whole pixel before rotation.
LintKit rescans automatically when your file changes. If a finding disappeared, your edit resolved the underlying problem. For example, changing a fill from a raw hex value to a library style removes the orphaned fill finding.This is expected — findings stay in sync with the current state of your file.
If you renamed or deleted tokens in Tokens Studio or your GitHub repository, Figma variables that referenced those tokens may now be broken. LintKit’s Broken Variables rule catches these disconnected references.To fix: detach the broken variable binding (keeps the current resolved value) and then re-bind to the correct variable. See Broken Variables for details.

​
Configuration problems

LintKit stores settings per user per plugin. Your configuration should persist when you close and reopen the plugin.If settings are resetting:
  1. Close and reopen cleanly. Settings save when the plugin runs — make sure you close the plugin (not just minimize Figma) and reopen it.
  2. Check browser storage (web app only). Clearing browser data or using incognito mode resets plugin storage. Use the Figma desktop app for reliable persistence.
  3. Reinstall as a last resort. Uninstalling resets settings, so only do this if settings aren’t persisting anyway.
Some rules require configuration before they produce findings:
RuleWhat to configure first
Spacing ScaleSet allowedSpacing values or configure baseSpacing
Corner RadiiReview allowedRadii defaults or enter your own
Grid AlignmentSet up column grid breakpoints
Duplicate StylesOnly runs in library files
Missing DescriptionsOnly runs in library files
Also check whether Tokens Studio strict mode is suppressing findings that match tokens.
If LintKit reports an overwhelming number of findings:
  1. Use selection scan. Select a single frame and fix it, then move to the next.
  2. Disable noisy rules. Turn off rules you’re not addressing right now. Start with 2-3 high-priority rules and add more as you go.
  3. Increase tolerances. If findings are too strict for your current design phase, increase spacingTolerance or colorTolerance.
  4. Focus on one category. Use the navigation tabs (Styles, Values, Components, etc.) to work through one category at a time.
When onboarding LintKit onto an existing file with many inconsistencies, start with Contrast and Broken Variables (always-on, high-value), then add Orphaned Fills and Naming, then gradually enable spacing and radii rules as you standardize.
When the Tokens Studio integration is enabled, token values take precedence over your manual configuration for the same rule. If you see unexpected values in your allowed spacing or radii lists:
  1. Check if the integration is enabled in Settings > Integrations
  2. Check which token type toggles are on (enforceColors, enforceSpacing, enforceRadii)
  3. Turn off the specific toggle for the rule you want to configure manually
For example, turning off tokensStudio.enforceSpacing reverts the Spacing Scale rule to your manual allowedSpacing values.

​
Feature requests and bug reports

If you’ve found a bug, have a feature request, or need help with something not covered in these docs:
  • Bug reports and feature requests: Email [email protected] with a description of the problem, what you expected to happen, and what actually happened. Screenshots or screen recordings are helpful.
  • Documentation feedback: If something in these docs is unclear, incorrect, or missing, let us know at [email protected].
When reporting a bug, include:
  • What you were doing when the problem occurred
  • What you expected to happen
  • What actually happened
  • Your Figma environment (desktop app or web, operating system)
  • Whether the problem is reproducible or intermittent