UI Component Selector

Translate the user's intended behavior into the right UI pattern without requiring them to know component terminology. Ground recommendations in The Component Gallery, then align them with the components already available in the current project.

Inputs

Use all available context:

• The user's plain-language description and whether they asked for advice, implementation, or modification of an existing interface.
• The current UI and trigger location, when modifying an existing interface.
• Read-only project evidence such as dependencies, lockfiles, imports, components.json, Tailwind configuration, and existing component files.
• The frontend framework, design system, and already-installed components. Do not introduce a new framework or component library merely to satisfy this workflow.

Workflow

1. Understand the interaction. Extract the user's goal, trigger, placement, content, modality, selection behavior, and whether the content is informational or actionable. Translate non-English descriptions into several concise English search concepts; do not rely on a literal translation or a single guessed component name.
2. Inspect the project. Identify the active framework and design system from project evidence. Prefer the project's existing components and conventions. If no design system is present, retain generic HTML, CSS, and JavaScript candidates.
3. Retrieve candidates. Search The Component Gallery for two to five plausible patterns. Open candidate component pages and use their canonical name, alternate names, description, related components, and Examples as evidence. Examples are reference cards with screenshots and outbound links, not guaranteed live demos.
4. Align with the project. Within each candidate page, prefer an Example from the detected design system. Otherwise prefer the same framework or technology. Record the Component Gallery page and the linked official component page. Before implementation, consult the current official documentation because the gallery can be incomplete or stale.
5. Eliminate semantic mismatches. Distinguish components by user purpose, not visual similarity. For example, use Select for choosing a form value, Combobox when the user can type or filter, Dropdown Menu for actions or navigation, and Popover for arbitrary anchored interactive content.
6. Decide or ask. If one candidate clearly satisfies the behavior and project constraints, briefly report the choice. Continue to implementation only when the user's original request authorized implementation. If two or more candidates remain meaningfully different, present the smallest useful set and wait for the user's choice or ask one question that separates them. Do not pause for cosmetic variants that do not change behavior.
7. Present the result. Make the result decision-ready. For every candidate, show its canonical name, project-specific component name when available, a short plain-language explanation, the important distinction, and links to the Component Gallery page and official documentation. Actively attempt to show a trustworthy visual preview for every presented candidate and identify the recommended candidate.

Delivery

Deliver the result in the user-visible response. Model-facing evidence is not delivery: opening an image with read, view, a browser, or another inspection tool does not count unless that preview is also surfaced to the user.

Keep the decision set small. Each candidate offered to the user must be one complete unit containing:

• its canonical and project-specific names, with the recommendation marked;
• a real preview from the matched Example or official component;
• a short explanation of the decisive difference;
• clickable Component Gallery and official component links.

In a Resolved result, fully present the selected candidate and mention rejected patterns briefly. In Needs choice, every selectable candidate must have the complete unit above.

Use the best user-visible capability available; do not require a named product tool. Prefer a native presentation only when it can display the required preview and links. Otherwise embed the freshly resolved image in the final message using the supported format, such as Markdown image syntax, or attach a page screenshot or faithful local render. A text-only choice control may collect the decision after the visual candidates, but it never replaces them.

An empty project is not a reason to skip external previews. Gallery image URLs may be used transiently in the current response but must not be persisted as stable data. When rendering success is observable, verify it; otherwise place a direct image link beside the embed as a fallback.

Use text-only output only after an actual visual-delivery attempt fails. State the failure and retain direct Example and official links. Do not substitute an ASCII or text schematic unless the user asks for one.

Before finishing or implementing, apply this delivery gate: every fully presented candidate has a user-visible preview or disclosed fallback, a Gallery link, and an official link. If not, continue retrieval or repair the response instead of treating the selection as delivered.

Output contract

End component selection in one of these states:

• Resolved: one component is clearly appropriate. Show its preview when the source provides one, report the evidence, and, if authorized, continue the user's implementation or modification request.
• Needs choice: two or more candidates remain valid. Recommend one, explain the decisive differences, present visual previews and links, and wait. Use the documented text-only fallback only after visual attempts fail.
• No match: the gallery or current design system has no suitable component. Say so explicitly and fall back to the current library's official documentation or a standards-based native implementation.

Boundaries

• Treat The Component Gallery as a discovery and comparison source, not the implementation source of truth.
• Do not change code when the user requested only identification, explanation, or evaluation.
• Do not choose solely from popularity, screenshot appearance, or name overlap.
• Do not hide uncertainty. When project detection or retrieval fails, say what could not be verified and present the best grounded fallback.