Component indexing is Builder’s AI-powered approach to automatically discover, analyze, and map design system components, icons, and tokens you have in Figma to the components in your codebase.
This comprehensive system reduces manual effort, improves design system adoption, and accelerates the design-to-code workflow.
- The
index-repocommand typically achieves 70% mapping accuracy and enables code generation that uses your design system components, icons, and tokens. - Once your repository has been indexed, use the
codecommand to continue generating code. Your generated code is now ready to make use of your own components and icons.
Component indexing solves the complex problem of Figma component mapping, which traditionally requires significant manual effort to validate whether mappings correctly translate design components into code components.
The system provides:
- Automated discovery: automatically discover and leverage customers’ design systems without manual mapping setup—this is the primary step and may be sufficient for most organizations.
- AI-assisted mapping: use AI to generate precise component mapping files—only needed when Automated Discovery doesn’t provide sufficient coverage.
The table below compares the manual component mapping process to Builder's AI-driven component indexing process.
| Manual | Component indexing | |
|---|---|---|
1 | Setup: open Figma file and Builder plugin, copy mapping command. | One-time setup: run repository indexing to discover design system automatically |
2 | Component selection: select from discovered code components. | Export: run code generation command. |
3 | Documentation: provide component documentation URLs for better AI results. | |
4 | Review and iterate: review AI-generated mappings, provide feedback, refine through multiple rounds. | |
5 | File management: choose save locations for each mapping file. | |
6 | Publish: upload all mappings to Builder Space. | |
7 | Export: run code generation command. |
The index-repo command analyzes your entire codebase to understand the component architecture and relationships. This automated discovery typically achieves 70% mapping accuracy and enables code generation that uses your design system components, icons, and tokens.
The index-repo command detects design tokens in your codebase. This enables AI code generation to understand all available icons, their variants, and proper usage patterns, as well as your design system's tokens for colors, spacing, typography, and other style properties.
When design tokens are detected, the system captures:
- Token definitions: CSS variables, SASS variables, and theme tokens
- Categorization: organized by type (colors, spacing, typography, elevation, shadows, etc.)
- Token values: actual values and their semantic meanings
- Usage context: where and how tokens are typically applied
Indexing design tokens improves AI-assisted code generation by:
- Using your actual design tokens instead of hardcoded values
- Maintaining design system consistency across generated code
- Applying semantic token names that match your system's conventions
- Ensuring generated styles align with your design language
The index-repo command detects and indexes icon libraries in your codebase. By indexing both components and icons, the system ensures AI-generated code uses only the icons and components available in your project, with correct imports, variants, and usage patterns.
When icon libraries are detected, the system captures:
- Complete inventory: all available icon names and their import paths
- Variants: styles such as Filled, Outlined, Rounded, Sharp, and TwoTone
- Usage patterns: common implementation examples and props
- Brand icons: logo and brand-specific icons with limited variants
Indexing icon libraries improves AI-assisted code generation by:
- Selecting appropriate icons that exist in your library
- Applying the correct import statements and icon variants
- Following your library’s usage conventions
- Preventing references to icons that don’t exist
To perform automated discovery, run the index-repo command from within your repository. This performs a three-phase analysis:
- Component discovery and grouping: scans for components and analyzes architectural relationships.
- Detailed component documentation: generates individual MDX files for component groups.
- Data storage: by default, uploads component information to Builder’s servers for remote access.
npx "@builder.io/dev-tools@latest" index-repoComponents are grouped based on architectural interdependency, not thematic similarity.
Components are grouped together when they have:
- Mandatory compositional architecture and can’t function without each other
- Exclusive required context dependencies
- Critical runtime dependencies
Components remain separate even if they:
- Share similar themes, such as a
Button,IconButton, andToggleButton - Use shared infrastructure, such as an
AreaChart,BarChart, andLineChart - Have visual similarity, such as a
Card,Panel, andModal
To get the most accurate results from index-repo, run the command directly inside your design system component repository rather than using the--designSystemPackage flag:
# Navigate to your design system repository
cd path/to/your-design-system
# Run indexing directly in the component library
npx "@builder.io/dev-tools@latest" index-repoRunning in the design system repository gives the AI full context for discovery and mapping, including:
- Richer context: full access to documentation, code comments, examples, Storybook stories, and tests that provide detailed component usage patterns.
- Complete discovery: captures all components, utilities, and design tokens along with their supporting materials.
- Enhanced documentation: leverages existing README files, JSDoc comments, and component examples to create more refined and accurate mappings.
If running within the design system repository isn’t possible, scope indexing to a specific package or all packages under a namespace:
# Focus on specific design system package
npx "@builder.io/dev-tools@latest" index-repo --designSystemPackage @mycompany/ui-components
# Index all packages under a scope
npx "@builder.io/dev-tools@latest" index-repo --designSystemPackage @mycompanyAI instructions improves code generation output and reduces redundancy in prompting instructions. This saves you money and time.
AI agents can produce sophisticated code while simultaneously making basic mistakes that contradict project conventions. Configuration files address this inconsistency by providing agents with project-specific guidelines and standards.
Fusion provides 3 ways to instruct the AI:
- Through an
AGENTS.mdfile. This file is an industry standard that can be used by several AI coding agents. Visit AGENTS.md for details. - Through several files placed within a
.builder/rules/directory. These files can be scoped to discuss specific files or topics. - Through one or more files called
.builderruleswhich can be placed within the root directory or any directory within your application. These configuration files can live side-by-side with the functional files that they describe.
All of these files work very similarly, and Fusion will process all of them. The key difference between them lies in how you wish to architect your application's instructions.
For more details on how to write your AI instructions, visit AI instruction best practices.
When debugging issues, keep the following in mind:
- Run the
index-repocommand whenever you add new components or change component architecture - Ensure your repository contains recognizable component patterns
- Use
--debugflag for detailed logging - Check that component files follow standard naming conventions
- Use
--forceif you’ve made significant component changes to existing components
For other issues and details, visit the Builder CLI API docs.
Once your components have been discovered and mapped, add the name of your design system to your builder.config.json file.
First, create a folder for your Builder workspace and add the builder.config.json file, for example:
/builder-workspace
builder.config.jsonNext, add the following to your builder.config.json file, replacing the string "my-design-system" with your project's name.
{
"repoIndexingConfig": {
"designSystems": [
"my-design-system"
]
}
}The index-repo command supports delta updates and CI/CD integration. By default, the command automatically handles adding new components, updating existing ones, and removing deleted components
The following YAML file for GitHub Actions runs the index-repo command on the main branch.
name: Update Component Index
on:
push:
branches: [main]
paths:
- "src/components/**"
jobs:
index-components:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 18
- name: Index repository components
run: npx "@builder.io/dev-tools@latest" index-repo --skipHeader --spaceId YOUR_SPACE_ID --designSystemName DESIGN_SYSTEM_NAME
env:
BUILDER_PUBLIC_KEY: ${{ secrets.BUILDER_PUBLIC_KEY }}
BUILDER_PRIVATE_KEY: ${{ secrets.BUILDER_PRIVATE_KEY }}For this YAML file to work, define the following values:
YOUR_SPACE_ID: Replace this variable within the file above with your Space's unique ID.DESIGN_SYSTEM_NAME: Replace this variable within the file above with the name of the design system. This was provided when first running theindex-repocommand. Visit your Design System Intelligence page for more details.BUILDER_PUBLIC_KEY: Set this environment variable with your Space's Public API key.BUILDER_PRIVATE_KEY: Set this environment variable with your Space's Private API key.
For more details on keys, visit Use Builder API key.
Visit Scoped component indexes next, or watch our livestream on how to Train AI on your design system.