Component indexing is Builder.io’s AI-powered approach to automatically discover, analyze, and map design system components from Figma to your codebase. This comprehensive system reduces manual effort, improves mapping accuracy, 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. - Once your repository has been indexed, use the
codecommand to continue generating code. Your generated code will now more readily make use of your own components.
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 & 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. |
Analyze 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.
npx "@builder.io/dev-tools@latest" index-repoThe command performs a 3-phase analysis:
- Component Discovery & 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.io’s servers for remote access.
Components 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.
Index your repository by using the following command from within your repository:
npx "@builder.io/dev-tools@latest" index-repoYour mapped components will be stored remotely, connected to your Builder Space.
For the highest quality mapping results, run the command directly within your design system component repository instead of 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-repoThis approach provides superior component discovery and analysis compared to using the--designSystemPackage flag because:
- 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, you can use these alternatives:
# 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 @mycompany
# Quick Indexing (skips detailed analysis)
npx "@builder.io/dev-tools@latest" code --url "figma-url" --indexIf you encounter problems, 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, use the code command for a streamlined workflow:
npx "@builder.io/dev-tools@latest" code --url "figma-url"This combines repository analysis and code generation in one command.
Learn more about Mapping components and review the Builder CLI API docs.