Component Decision Tree

Component decision tree

A skill for building decision trees that map user intents and requirements to specific component selections. The primary output is a set of "Choosing between…" pages in the docs, one per cluster of confusable components, written as the questions a senior designer would ask; the same trees can be written as YAML for tooling when something will read it. Both reduce the guesswork that leads to component misuse, duplication, and inconsistency.

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

Component selection is the first decision in any design system interaction, and it is the one that AI agents get wrong most often. The failure mode is not random — it follows predictable patterns. An agent selects a Modal when a Dialog was appropriate. It uses a Card where a List Item fits better. It creates a custom component because it could not find the existing one that serves the need.

These errors have the same root cause: the agent does not have a decision framework. It has a list of components (if it has anything at all) and it pattern-matches the user's request against component names and descriptions. This works when the match is obvious ("I need a button" → Button) and fails when the match requires judgment ("I need to show a collection of items that users can filter and sort" → is that a Table, a DataGrid, a List with filters, or a custom composition?).

Decision trees encode the judgment. Instead of relying on an agent's ability to infer the right component from a description, the tree asks a structured sequence of questions that narrow the selection to the correct component. The questions are the same ones a senior designer or developer would ask when advising a junior team member.

The practical output is a page a human reads and an agent is pointed at from AGENTS.md (agent-instructions links the choosing pages). A YAML form of the same tree is useful only when a tool will traverse it; write it on request, not by default, so there is one thing to keep current.

Boundaries

This skill produces decision trees for component selection — choosing between components. It does not document how to use a single component once selected (use usage-guidelines for that) or generate component metadata schemas (use metadata-schema-generator). If the system has fewer than 5 components, a decision tree adds overhead without value — a simple component index is sufficient. If no component inventory exists, run component-audit or codebase-index first to establish one.

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.component_paths — directs scanning to component directories
• system.category_model — determines top-level decision tree branches (atomic, functional, custom)
• integrations.* — component data sources (see below)
• decision_tree.output_format — markdown (default: pages in docs/choosing/), yaml or json (machine-readable trees in .ai/decision-trees/ as well as the pages)

Auto-pull integrations

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

• Read the published component library from integrations.figma.file_key
• Extract component names, descriptions, and variant structures
• Use descriptions as input for decision node generation

Storybook (integrations.storybook.enabled: true):

• Fetch the story index for a complete component list
• Extract documented use cases from story titles and descriptions

Codebase index (.ai/index/component-inventory.yml):

• If a codebase index exists, load the component inventory and relationship graph
• Use category assignments and relationship data to inform tree structure

Step 1: Map the component landscape

Before building decision trees, understand what components exist and how they cluster.

Component inventory: List every component with its purpose and category. If a codebase index exists, use it. If not, scan the component directories.

Functional clusters: Group components by the user need they serve, not by their technical category. A single user need often spans multiple components. The two tables below are illustrative: build yours from the scanned inventory, not from these names.

Overlap analysis: Identify components with overlapping use cases. These are the decision points where agents (and humans) get confused. In real output, each distinguishing factor cites where it came from (the system's docs, source, or the user); otherwise mark it proposed:

Provenance rule. Two hard rules for everything this skill writes:

• Every resolve: names a component that exists in the scanned inventory. If the right answer is a component the system doesn't have, say so in the summary rather than resolving to it.
• Every leaf rationale and distinguishing factor carries a basis: a docs or source path, user, or proposed. Selection logic you inferred from general design practice is proposed until the team confirms it. See "Every figure and fact needs a source" in the output-discipline knowledge note.

Ask for or confirm:

• Are there components that teams frequently confuse or misuse? (These are high-priority decision points)
• Are there component selection decisions that are currently undocumented and rely on tribal knowledge?
• Are there recent cases where an AI agent or a new team member selected the wrong component?

Step 2: Build the intent taxonomy

Define the intents that drive component selection. Intents are what the user or agent is trying to accomplish, expressed independently of any specific component.

Intent categories

Cover the categories the inventory actually needs; typical ones:

• Display — show information (a value, a list, a table, a status, a notification, contextual help, media)
• Input — collect information (text, a choice from options, a date, a boolean, a file, a search query, a complex form)
• Action — let the user do something (primary or secondary action, navigate, confirm a destructive action, open a menu, toggle)
• Layout — organise content (group, separate, create navigable structure, contain an interactive flow)

Intent format

intents:
  display_notification:
    description: "Show feedback about an action or system event"
    qualifiers:
      persistence: ["transient", "persistent", "dismissible"]
      severity: ["success", "warning", "error", "info"]
      position: ["inline", "overlay", "page-level"]
      blocking: ["blocks_interaction", "non_blocking"]

Step 3: Build the decision trees

For each functional cluster, build a decision tree that maps intents and qualifiers to component selections.