> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lintkit.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
Determine which libraries your team should be using. These are typically your organization's official design system libraries.
In **Settings**, populate `approvedLibraryKeys` with the library key strings for your approved libraries. You can find library keys in LintKit's **Sources** panel.
LintKit flags all instances from unapproved libraries. Review the findings to identify which unofficial libraries are in use.
* 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
* **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
**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.
**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.
**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.
**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
Click the finding to see the full instance chain from the component down to its deepest nested instance.
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
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.](/features/pricing)
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
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.](/features/pricing)
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
Click the finding to identify which style or component needs a description.
* 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
* **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).