Refine design system indexes

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.

Before you begin

All corrections require re-indexing to take effect. If you are only making changes to a single token or component or list of them this can be done with the --components flag in the CLI. Read more about the index-repo command in Design system indexing, which covers index-repo extensively.

Overview of methods

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.md or .builderrules to guide the indexing process.
Exclude files: remove specific files from the index.

Each method has its use cases, which the following sections explore.

Update source material (recommended)

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.

Example

A design system might include both a generic TextInput component and a specialized FieldInput component. Without clear documentation, AI-generated code might use TextInput everywhere, even when FieldInput is the better choice for form contexts.

/* 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(''); ... }

Add correction rules

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.

Example

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`

Exclude files

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 exclusion

When 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.

Include migration guidance

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`

Reindexing components

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 index-repo to target just those documents.

npx builder.io@latest index-repo --components="Button,Card"

For tokens and icon libraries, rerun the index:

npx builder.io@latest index-repo

Exclusions and existing documents

Exclusions apply to future indexing. If a file was already indexed, rerun the index to ensure it is excluded.

What's next

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 .builderrules that 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.

Was this article helpful?