Component rules

Maintain component health and library governance

Component rules help you maintain healthy component usage and enforce library governance across your team. They catch broken instances, unnecessary wrappers, performance bottlenecks from deep nesting, and components that drift outside your approved libraries.

Unapproved Libraries

Default: On | Severity: error

Flags component instances that come from libraries not on your approved list. This prevents your file from accumulating dependencies on unofficial, outdated, or deprecated libraries.

What it detects

Any instance whose source library is not in your approved library list. For example:

Unapproved library — 14 instances use components from Old Design System v2. This library is not in your approved list.

Disconnected instances (where the source component cannot be found at all) get their own separate finding:

Disconnected instances — 3 instances have lost their connection to a source component.

When to enable it

Enable when your organization has designated approved libraries and wants to prevent teams from using unofficial ones. Keep the approvedLibraryKeys list empty (the default) if you want to skip this rule — an empty list means all libraries are allowed.

How auto-approval works

You do not need to manually approve every library your team uses. LintKit automatically identifies the most-used remote library in your file and auto-approves any libraries that share a key prefix with it.

For example, if your file mostly uses components from Acme Design System, and your organization also publishes Acme Icons and Acme Charts with the same key prefix, all three are auto-approved automatically.

How to set up approved library keys

1. Identify your approved libraries

   Determine which libraries your team should be using. These are typically your organization’s official design system libraries.

2. Add library keys to configuration

   In Settings, populate approvedLibraryKeys with the library key strings for your approved libraries. You can find library keys in LintKit’s Sources panel.

3. Run a scan

   LintKit flags all instances from unapproved libraries. Review the findings to identify which unofficial libraries are in use.

4. Fix by replacing or detaching

   • Replace instances with components from an approved library.
   • Click Apply Fix to detach unapproved instances (recursively detaches nested instances too).
   • Click Ignore for instances you want to keep intentionally.

Configuration

Key	Default	Description
approvedLibraryKeys	[]	Library key strings for approved libraries. Empty means all libraries are approved (rule produces no findings).

Edge cases

Special cases

• Empty approved list. When approvedLibraryKeys is empty, all libraries are considered approved and this rule produces zero findings. This is the default.
• Local components. Components defined directly in the file (not from a library) are always skipped by this rule. Use the Components rule to review local components.
• Disconnected instances. Instances with no main component (source deleted or library removed) get their own finding separate from unapproved library findings.

---

Components

Default: On | Severity: warn

A multi-check rule that detects four types of component health problems. Each sub-check targets a different common problem with component usage.

What it detects

Wrapper groups

Severity: info

What gets flagged: Groups that wrap a single component instance.

Example scenario: You drag a button from your library, then accidentally group it (Cmd+G). Now there is a group wrapping a single button instance. This extra layer breaks override propagation, makes selection harder (you have to double-click through the group), and inflates the layer tree.

Example finding:

Wrapper group Group 1 wraps a single instance of Button/Primary. Consider flattening.

Why it matters: Wrapper groups break component overrides, add unnecessary nesting, and confuse developers who see an extra group in the layer tree.

Fix: Click Apply Fix to flatten (ungroup) the wrapper. The instance moves up to the group’s parent.

Local components

Severity: info

What gets flagged: Components defined directly in the file rather than sourced from a library.

Example scenario: A designer creates a Card component directly in a project file instead of using the team’s shared library. Other designers in the same project cannot access it, and it will not stay in sync with the design system.

Example finding:

Local component Card/Default is defined in this file, not sourced from a library. 7 local components found.

Why it matters: Local components are not inherently wrong — they are useful for file-specific patterns. But they may indicate components that should be promoted to your shared library.

Fix: None (informational only). Review local components and decide whether to promote them to your library.

Broken instances

Severity: error

What gets flagged: Instances where the source component can no longer be found.

Example scenario: Your team’s library was reorganized and the OldButton component was deleted. Files that used OldButton now contain broken instances that display a placeholder or stale content.

Example finding:

Broken instance — source component not found. 3 broken instances detected.

Why it matters: Broken instances silently fall back to their last known state. They will not receive updates, and developers may build features based on stale or incorrect components.

Fix: Click Apply Fix to detach the broken instance. LintKit recursively detaches all nested instances within it. After detaching, replace the detached layers with the correct component from your current library.

Instances of local components

Severity: info

What gets flagged: Instances that reference a local component (defined in the same file) rather than a library component.

Example scenario: A designer created a Tag component locally, then used 15 instances of it across the file. If the team later creates an official Tag component in the library, these local instances will not receive library updates.

Example finding:

Local instances — 15 instances reference the local component Tag/Default instead of a library component.

Why it matters: Helps you identify which local components have significant usage and should be migrated to a shared library.

Fix: None (informational only). Replace local instances with library instances after migrating the component.

When to enable it

Keep this rule on (it is the default) for all production files. The broken instances sub-check (severity: error) is particularly important because broken instances silently degrade file quality.

---

Nested Components

Default: On | Severity: info

Detects components with deeply nested instance hierarchies that may cause performance problems in Figma.

What it detects

LintKit counts how many levels of nested instances exist inside each component and component set. A component that contains an instance, which contains another instance, which contains another instance, has a nesting depth of 3.

Example finding at warning level:

Deep nesting — PageLayout/Default has 5 levels of nested instances. Instance chain: PageLayout > Header > NavigationBar > NavItem > Icon

Example finding at error level:

Excessive nesting — DashboardView/Analytics has 7 levels of nested instances. Estimated node count: 2,400+ nodes.

Why deep nesting is bad for performance

Each level of instance nesting multiplies the number of nodes Figma has to process. A component with 3 levels of nesting might expand to hundreds of nodes; 6 levels can expand to thousands. This causes:

1. Slow loading. Files with deeply nested components take longer to open and navigate.
2. Sluggish editing. Every edit to a deeply nested component triggers recalculation across all its instances.
3. Memory pressure. Figma loads all nested instances into memory, which can cause crashes on large files.
4. Slow scans. LintKit itself takes longer to scan deeply nested structures because it must resolve each instance chain.

When to enable it

Keep this on (it is the default) to catch performance bottlenecks. Disable only if your team intentionally uses deep nesting and understands the performance tradeoffs.

How to fix findings

1. Review the nesting chain

   Click the finding to see the full instance chain from the component down to its deepest nested instance.

2. Identify flattening opportunities

   Look for levels of nesting that add no value. Common patterns to simplify:

   • A component that only wraps a single instance of another component
   • Components that re-export library components with no added value
   • Layout components that could use direct children instead of sub-components
3. Restructure the component

   Flatten unnecessary nesting levels by moving children up in the hierarchy. Consider using slots (empty frames that consumers fill) instead of deeply nested instance structures.

There is no auto-fix for this rule because restructuring components requires design judgment.

Configuration

Key	Default	Description
componentStructure.checkNestedComponents	true	Toggle this rule on or off
componentStructure.nestingWarningThreshold	4	Nesting depth that triggers a warn severity finding
componentStructure.nestingErrorThreshold	6	Nesting depth that triggers an error severity finding

Findings are sorted by nesting depth, deepest first, so the worst performance bottlenecks appear at the top.

---

Hidden Components

Default: On | Severity: info

This rule only produces findings in library files. Learn more about library-only rules.

Detects main components that are hidden from Figma’s publishing flow. This gives library maintainers an inventory of which components consumers cannot discover.

What it detects

In Figma, a component whose leaf name (the last segment after /) starts with a dot (.) or underscore (_) is excluded from library publishing. Consumers of your library will not see these components in the assets panel.

Example findings:

Hidden component Icons/.Internal — leaf name .Internal starts with a dot. Not visible to library consumers. Hidden component Primitives/_BaseButton — leaf name _BaseButton starts with an underscore. Not visible to library consumers.

When to enable it

Enable when auditing a library file to review which components are hidden. This helps catch components that were hidden intentionally versus accidentally.

How to fix findings

This rule is informational only — there is no auto-fix. Review each hidden component and decide:

• Keep hidden if the component is an internal primitive (like _BaseButton) that consumers should not use directly.
• Unhide by renaming the leaf name to remove the dot or underscore prefix if the component should be visible to consumers.

Edge cases

How leaf names are determined

Only the last segment after the final / in the component name is checked. A component named Icons/.Internal is flagged because .Internal starts with a dot. A component named .Hidden/Button is not flagged because the leaf name is Button (which does not start with a dot or underscore).

---

Missing Descriptions

Default: Off | Severity: info

This rule only produces findings in library files. Learn more about library-only rules.

Detects styles and components that have no description. Descriptions are essential for library consumers — they explain when and how to use each asset.

What it detects

Any local style or component/component set with an empty or missing description field. For example:

Missing description — paint style Brand/Primary has no description. Missing description — component Button/Primary has no description.

When to enable it

Enable when you are preparing a library for publication or running a library scan. Good descriptions help consumers choose the right style or component without guessing. This rule is off by default because it produces many findings in undocumented libraries.

How to fix findings

1. Review the asset

   Click the finding to identify which style or component needs a description.

2. Apply the auto-generated description or write your own

   • Click Apply Fix to apply an auto-generated description based on the asset name and type (for example, a paint style named Brand/Primary gets a description like “Primary brand color”).
   • For more useful descriptions, write your own that explains when to use the style or component, not just what it is.

Edge cases

Scope differences

• Styles are checked across all pages (descriptions are a file-level property).
• Components are checked on the current page only (to avoid slow multi-page loading).