/component-decision-tree

name: component-decision-tree
description: "Write \"choosing between\" pages (docs/choosing/) that route an intent to the right component via narrowing questions; YAML trees on request. Triggers: which component should I use, choose between X and Y, dialog vs drawer, selection guide. One chosen component: usage-guidelines."
allowed-tools: Read, Write, Grep, Glob, Bash(cat:*), Bash(find:*), Bash(head:*), Bash(ls:*)
references:
  - ../../knowledge-notes/ai-readiness.md
  - ../../knowledge-notes/component-bestiary-reference.md
  - ../../knowledge-notes/output-discipline.md

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.

| User need | Components that serve it | |---|---| | Show a notification | Toast, Banner, Alert, InlineMessage, Snackbar | | Collect user input | Input, TextArea, Select, Combobox, DatePicker, Checkbox, Radio, Switch | | Navigate between views | Tabs, Sidebar, Breadcrumb, Pagination, BottomNav | | Display a collection | Table, DataGrid, List, CardGrid, Timeline | | Confirm an action | Dialog, ConfirmationModal, AlertDialog | | Show contextual info | Tooltip, Popover, HoverCard,