Component indexing is Builder’s AI-powered approach to automatically discover, analyze, and map design system the components 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-repo
command typically achieves 70% mapping accuracy and enables code generation that uses your design system components. - Once your repository has been indexed, use the
code
command to continue generating code. Your generated code is now ready to 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 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. |
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-repo
This command performs a 3-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.
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-repo
Your mapped components are 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-repo
This 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" --index
When debugging issues, keep the following in mind:
- Run the
index-repo
command whenever you add new components or change component architecture - Ensure your repository contains recognizable component patterns
- Use
--debug
flag for detailed logging - Check that component files follow standard naming conventions
- Use
--force
if 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:
{
"repoIndexingConfig": {
"designSystems": [
"my-org-react-design-system"
]
}
}
From there, 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.
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 the
index-repo
command. 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.
Learn more about Mapping components and review the Builder CLI API docs.