Refine your indexed content to help you achieve more accurate and useful documentation. While some issues become apparent when you review the generated documentation, some only surface during code generation.
All corrections require re-indexing to take effect. If you are only making changes to a single component or list of components this can be done with the --components flag in the CLI. Read more about the index-repo command in Component indexing, which covers index-repo extensively.
You have three options for refining indexing outputs:
- Update source material (recommended): modify your component code or token definitions directly.
- Add correction rules: use
AGENTS.mdor.builderrulesto guide the indexing process. - Exclude files: remove specific files from the index.
Each method has its use cases, which the following sections explore.
The best way to refine your design system index is to improve your source material directly. This could mean adding comments to component source files, CSS comments to tokens, or clarifying type definitions.
When to use this method
- You have access to modify the source code directly.
- The issue stems from missing or unclear information in your files.
- You want to ensure long-term accuracy across all regenerations and information consumption channels.
Why this is recommended
- Single source of truth: anyone viewing your code or documentation sees the same information as the generated docs.
- Permanent solution: documentation stays accurate with every re-index.
- Broader benefit: helps all contributors working with your design system not just the code generations.
An example design system has multiple types of input components. And code that is generated is using the generic TextInput when a better alternative might be FieldInput. This can occur because there is not enough information available to designate how the inputs differ.
/* Using primitive directly */
<Field>
<TextInput value={name} onChange={setName} />
</Field>
/* Instead of using the appropriate semantic token */
<Field>
<FieldInput value={name} onChange={setName} />
</Field>Solution
Add a comment to the component to designate its importance of use within the Field Component:
import React, { useState } from 'react';
/**
FieldInput should always be used in place of
Input when within a Field Component.
**/
function FieldInput() {
// Declare state variables for each input field
const [name, setName] = useState('');
...
}When you can't modify source files or need to add broader context, you can provide guidance through rules files. The indexing process reads these files and applies the rules during generation.
When to add correction rules
- You need a quick fix without modifying your codebase or you don't have permission to modify the source files
- You want to quickly test if adding context will correct the issue you are experiencing
How to add rules
Create or update an AGENTS.md or .builderrules file in the root of the project where you are indexing the design system.
Common use cases for rules
- Clarify misleading names: explain when names don't match expected behavior.
- Add usage restrictions: document constraints not obvious from the API.
- Document undocumented behavior: explain implementation details that affect usage.
- Provide design context: share reasoning behind design decisions.
- Link related items: explain how components or tokens work together.
One example might be that the design system index includes primitives that should not be used when a semantic or component-specific token exists. This can cause code to get generated that is referencing an internal implementation.
/* Using primitive directly */
.button {
background: var(--blue-500);
padding: var(--space-4);
}
/* Instead of using the appropriate semantic token */
.button {
background: var(--color-primary);
padding: var(--spacing-button);
}Solution
Add a rule to not include primitives in the design system index:
## Design system indexing rules
When indexing design tokens be sure to:
- only include semantic or component-specific tokens.
- primitives with the following formats should not be included:
`--(color|space|spacing)-number`Sometimes the best solution is to remove files from the index entirely. This is useful for internal utilities, deprecated items, or components that shouldn't be documented.
Add exclusion rules to your AGENTS.md or .builderrules file:
## Indexing Exclusions
Exclude the following files from Design System indexing:
- `path/to/file.tsx` - Brief reason for exclusion
- `path/to/directory/**/*` - Brief reason for exclusionWhen to exclude files
- Files contain internal or deprecated components or tokens.
- Items have misleading APIs with better alternatives available.
- Work-in-progress features not ready for documentation.
- Implementation details not meant for consumers.
When you exclude deprecated items, describe alternatives.
## Deprecated Components/Tokens - Do Not Index
- OldComponent is deprecated. Use NewComponent instead.
**Migration guide:**
- Replace `<OldComponent>` with `<NewComponent>`
- Update prop names: `oldProp` → `newProp`After making any corrections, you must trigger re-indexing for changes to take effect. If your changes are isolated to a specific document or set of documents you can rerun the repo-index to target just those documents.
npx @builder.io/dev-tools repo-index --components="Button,Card"For tokens and icon libraries, rerun the index:
npx @builder.io/dev-tools repo-indexExclusions apply to future indexing. If a file was already indexed, rerun the index to ensure it is excluded.
Learn more about configuring AI tools for your project.
- Project configuration files: learn how to guide AI code generation with configuration files like
AGENTS.md,.builder/rules/, and.builderrulesthat define project-specific standards and conventions - AGENTS.md: Configure AI development tools across your workflow with
AGENTS.md, a standardized file that defines project conventions, setup commands, and testing requirements in one central location.