Codebase Index

Codebase index

A skill for generating a pre-computed, machine-readable index of a design system's codebase. The index contains three pieces: a component inventory, a relationship graph, and summary statistics. Together they form a queryable map that eliminates the need for AI agents or developers to explore the codebase from scratch every time they need to understand the system.

Before you begin: verify references

Confirm that every path in this skill's frontmatter references: exists relative to this SKILL.md. If any is missing, stop: the install is incomplete, usually because a flattening installer (for example npx skills install) dropped the repo-root knowledge-notes/ directory. Tell the user to reinstall by a method in 1-INSTALL.md and run verify-install.sh from the install root. Proceed without the references only if the user explicitly says to, and then say in the output that it was produced without the pack's reference material.

Context

An agent exploring a codebase from scratch is slow and misses things; an agent loading a pre-computed index gets the whole picture in a few thousand tokens. This skill writes that index, and it is the pack's single producer of the component inventory and dependency graph: token-audit, component-audit, docs-coverage, component-decision-tree and agent-instructions read .ai/index/ rather than building their own. Run it after adding or removing components, and commit the output alongside the code.

Configuration

If .ds-ops-config.yml exists, follow the configuration-and-recurring knowledge note (../../knowledge-notes/configuration-and-recurring.md) for loading, integration fallbacks and recurring runs. This skill reads:

• system.framework — pre-selects framework detection
• system.component_paths — overrides default component directory scanning
• system.category_model — atomic design, functional, or custom categorisation
• integrations.* — component data sources (see below)
• recurring.* — delta against the previous index (see Recurring workflow)

Auto-pull integrations

Figma MCP (integrations.figma.enabled: true):

• Read the published library from integrations.figma.file_key
• Cross-reference the Figma component inventory against the code inventory to detect components that exist in design but not in code (or vice versa)
• Pull description status per component to populate the metadata coverage field

Storybook (integrations.storybook.enabled: true):

• Fetch the story index from integrations.storybook.url/index.json
• Extract component list and documentation status
• Use as a secondary source for component discovery

GitHub (integrations.github.enabled: true):

• Pull PR activity for recency signals

Step 1: Detect the framework and structure

Scan the project root to determine:

• Framework: React (JSX/TSX), Vue (SFC), Svelte, Astro, Angular, Web Components, or mixed
• Component directories: Where components live — scan common locations: src/components/, src/lib/, components/, packages/, and any paths in tsconfig.json or framework config
• Category model: How components are organised — atomic design (atoms/, molecules/, organisms/), functional (forms/, navigation/, feedback/), flat, or monorepo packages
• Styling approach: CSS modules, CSS-in-JS, Tailwind, SCSS, or design tokens — this determines how to trace token dependencies

If no component files are found under any candidate root, stop and ask where they live; don't write an empty index.

Ask for or confirm (skip questions already answered by config or detection):

• The component source root if auto-detection finds multiple candidates
• Whether there are components in non-standard locations (e.g., a shared utils/ directory with reusable UI primitives)
• Whether to include internal/private components in the index (underscore-prefixed, internal/ directories, components not re-exported from barrel files)

Framework detection rules:

Step 2: Scan and build the component inventory

For every component file found, extract:

• Name: The component's exported name
• Path: Relative path from project root
• Category: Based on the category model (atom, molecule, organism, etc.) or functional category (navigation, form, feedback, layout, data display)
• Metadata status: Whether the component has structured metadata (a .metadata.ts, .metadata.json, description in Storybook, JSDoc/TSDoc block, or Figma description)
• Export type: Default export, named export, or re-exported through a barrel file
• Token bindings: the design tokens the component's styles reference (var(--color-action-primary), $space-gap, theme.colors.primary, Tailwind utilities that map to configured tokens). Record the token names as the codebase writes them. This is the token-to-component edge that token-audit and component-audit read for blast radius, so they don't each build a second graph

What counts as a component:

• Files that export a renderable element (JSX, template, render function)
• Files explicitly registered in a component index, barrel file, or Storybook config
• Exclude: pure utility functions, hooks/composables (unless they return JSX), type definitions, test files, story files

Category assignment:

• If the directory structure encodes categories (atomic design folders, functional folders), use directory position
• If the structure is flat, infer from component characteristics: components with no child components are atoms/primitives, components that compose other system components are compounds, components with significant built-in logic or product-specific context are features
• If uncertain, assign uncategorised and flag for manual review

Inventory format

Produce the inventory in YAML for readability and token efficiency:

components:
  Button:
    path: src/components/atoms/Button/Button.tsx
    category: atoms
    metadata: true
    tokens: [--color-action-primary, --color-on-action, --space-inset-md]
  Card:
    path: src/components/molecules/Card/Card.tsx
    category: molecules
    metadata: true
  DataTable:
    path: src/components/organisms/DataTable/DataTable.tsx
    category: organisms
    metadata: false

Step 3: Build the relationship graph

For every component in the inventory, trace two relationships:

• uses: Which other system components does this component import and render?
• usedBy: Which other system components import and render this component?

How to trace relationships:

1. Parse import statements in each component file
2. Resolve each import specifier before filtering. In a monorepo, @acme/button is a workspace package, not an external dependency — map workspace package names (from package.json workspaces, pnpm-workspace.yaml, or equivalent) and tsconfig.json paths aliases (@/components/*) to their source directories. Then filter to imports that resolve to components in the inventory, and drop genuine third-party packages, utility imports and type-only imports
3. For each import, verify it's actually rendered in the template/JSX (an unused import is not a relationship)
4. Record the relationship bidirectionally — if Card imports Button, then Card uses Button and Button usedBy Card

Deep tracing rules:

• Follow dependency chains to their leaves. If a page imports a layout, and the layout imports a nav, and the nav imports a link and an icon — the full chain matters for understanding which atoms actually appear on that page.
• Components with uses: [] (empty) are leaf nodes — they have no internal dependencies on other system components. These are the terminal nodes in the graph.
• Components with usedBy: [] (empty) are root nodes — nothing else in the scanned repo renders them. Label these "no in-repo consumers", not orphans or unused: a public component exported from the package entry point is meant to be consumed by product repos this index doesn't scan. Only non-exported components with no in-repo consumers are worth flagging, and even then as candidates.
• Before recording any "no in-repo consumers" result, run a positive control: confirm the import and render matching finds a component you know is used (e.g. Icon inside Button). If it doesn't, the matching is wrong for this codebase — fix it before writing the graph.

Instance counting: Import count and instance count are different metrics. A page might import Button once but render it five times. Instance counting requires parsing templates, not just import statements.

• Count tags matching <Name[\s/>] — the trailing space, / or > stops <Button from also matching <ButtonGroup. Resolve import aliases first (import { Button as Btn } means count <Btn)
• Namespace imports render as <UI.Button — match <Namespace\.Name[\s/>] (escape the dot) for each namespace import
• In Vue templates, components can be written in kebab-case: match <button-group[\s/>] as well as <ButtonGroup[\s/>]
• Detect slot/children components: if Button contains a <slot /> and someone writes <Button><Icon /></Button>, the Icon instance belongs to the parent scope, not to Button's internals. Don't recurse into slot content for instance counting.