Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(cli): semantic keyword search for component discovery (#1053)

Joey8e317e23cc6b
diff --git a/packages/cli/src/commands/component.test.mjs b/packages/cli/src/commands/component.test.mjs
index fccedd8309..76a76efc12 100644
--- a/packages/cli/src/commands/component.test.mjs
+++ b/packages/cli/src/commands/component.test.mjs
@@ -505,3 +505,48 @@ describe('findExternalComponentDoc', () => {
expect(result).toBeNull();
});
});
+
+
+describe('searchComponents', () => {
+ it('finds Collapsible when searching "accordion"', async () => {
+ const {searchComponents, discoverComponents} = await import('./component/index.mjs');
+ const components = discoverComponents('packages/core');
+ const results = await searchComponents('accordion', 'packages/core', components);
+ expect(results.length).toBeGreaterThan(0);
+ expect(results[0].name).toBe('Collapsible');
+ expect(results[0].score).toBe(90);
+ });
+
+ it('finds Dialog when searching "modal"', async () => {
+ const {searchComponents, discoverComponents} = await import('./component/index.mjs');
+ const components = discoverComponents('packages/core');
+ const results = await searchComponents('modal', 'packages/core', components);
+ expect(results[0].name).toBe('Dialog');
+ expect(results[0].score).toBe(90);
+ });
+
+ it('returns multiple matches for ambiguous terms like "select"', async () => {
+ const {searchComponents, discoverComponents} = await import('./component/index.mjs');
+ const components = discoverComponents('packages/core');
+ const results = await searchComponents('select', 'packages/core', components);
+ const top90 = results.filter(r => r.score === 90);
+ expect(top90.length).toBeGreaterThan(1);
+ const names = top90.map(r => r.name);
+ expect(names).toContain('Selector');
+ });
+
+ it('finds exact name matches with score 100', async () => {
+ const {searchComponents, discoverComponents} = await import('./component/index.mjs');
+ const components = discoverComponents('packages/core');
+ const results = await searchComponents('Button', 'packages/core', components);
+ expect(results[0].name).toBe('Button');
+ expect(results[0].score).toBe(100);
+ });
+
+ it('returns empty array for complete gibberish', async () => {
+ const {searchComponents, discoverComponents} = await import('./component/index.mjs');
+ const components = discoverComponents('packages/core');
+ const results = await searchComponents('zzzzzzzzzzz', 'packages/core', components);
+ expect(results.length).toBe(0);
+ });
+});
diff --git a/packages/cli/src/commands/component/index.mjs b/packages/cli/src/commands/component/index.mjs
index 89b2d7d6f7..814b319827 100644
--- a/packages/cli/src/commands/component/index.mjs
+++ b/packages/cli/src/commands/component/index.mjs
@@ -30,7 +30,7 @@ import {
ensureImportStatement,
extractProps,
} from '../../lib/component-legacy.mjs';
-import {findClosestComponents} from '../../lib/string-utils.mjs';
+import {findClosestComponents, searchComponents} from '../../lib/string-utils.mjs';
import {resolveTheme} from '../../lib/resolve-theme.mjs';
import {getRunPrefix} from '../../utils/package-manager.mjs';
@@ -174,27 +174,39 @@ export function registerComponent(program) {
}
if (!readmePath) {
- // Try fuzzy matching
const components = discoverComponents(coreDir);
- const closest = findClosestComponents(dirName, components);
-
- if (closest.length === 1) {
- resolvedName = closest[0].name;
- readmePath = findComponentReadme(coreDir, resolvedName);
- if (readmePath) {
- console.log(`Did you mean ${resolvedName}?\n`);
- }
- } else if (closest.length > 1) {
- console.error(`Component "${name}" not found. Did you mean one of these?\n`);
- for (const match of closest) {
- console.error(` ${match.name}`);
+ const results = await searchComponents(dirName, coreDir, components);
+
+ if (results.length > 0) {
+ const topScore = results[0].score;
+ const topTied = results.filter(r => r.score === topScore);
+ const secondScore = results.length > topTied.length
+ ? results[topTied.length].score : 0;
+ const gap = topScore - secondScore;
+
+ if (topScore >= 90 && topTied.length === 1 && gap >= 20) {
+ // Crystal clear single winner: show docs directly
+ resolvedName = topTied[0].name;
+ readmePath = findComponentReadme(coreDir, resolvedName);
+ if (readmePath && topScore < 100) {
+ console.log(`Showing results for ${resolvedName} (matched ${topTied[0].reason})\n`);
+ }
+ } else {
+ // Multiple strong matches or ambiguous: show options
+ // Include everything within 20 points of the top, min 2, max 5
+ const threshold = Math.max(topScore - 20, 1);
+ const candidates = results.filter(r => r.score >= threshold).slice(0, 5);
+ if (candidates.length < 2) candidates.push(...results.slice(candidates.length, 2));
+
+ console.error(`No component named "${name}". Did you mean:\n`);
+ for (const match of candidates) {
+ console.error(` ${match.name} (${match.reason})`);
+ }
+ console.error(`\nRun \`${run} xds component <name>\` to view docs.`);
+ process.exit(1);
}
- console.error('');
- process.exit(1);
- }
-
- if (!readmePath) {
- console.error(`Error: Component "${name}" not found.`);
+ } else {
+ console.error(`No component named "${name}".`);
console.error(`Run \`${run} xds component --list\` to see available components.`);
process.exit(1);
}
@@ -237,4 +249,4 @@ export {discoverExternalPackages} from '../../utils/paths.mjs';
export {loadDocs} from '../../lib/component-loader.mjs';
export {formatFull, formatCompact, formatBrief, formatProps, formatBriefAll} from '../../lib/component-format.mjs';
export {cleanReadme, extractCompact, extractBrief, ensureImportStatement, extractProps} from '../../lib/component-legacy.mjs';
-export {levenshteinDistance, findClosestComponents} from '../../lib/string-utils.mjs';
+export {levenshteinDistance, findClosestComponents, searchComponents} from '../../lib/string-utils.mjs';
diff --git a/packages/cli/src/lib/string-utils.mjs b/packages/cli/src/lib/string-utils.mjs
index ffac63abfe..8ccb7f5c19 100644
--- a/packages/cli/src/lib/string-utils.mjs
+++ b/packages/cli/src/lib/string-utils.mjs
@@ -1,5 +1,5 @@
/**
- * @file String utilities — fuzzy matching for component names
+ * @file String utilities — fuzzy matching and semantic search for component names
*/
export function levenshteinDistance(a, b) {
@@ -37,6 +37,152 @@ export function findClosestComponents(name, components, maxDistance = 3) {
}
/**
- * Resolve the import path for a component.
- * Returns e.g. '@xds/core/Table' or '@xds/core' depending on package.json exports.
- */
\ No newline at end of file
+ * Unified component search that scores matches across multiple signals:
+ * name similarity, keyword matches, and description/feature text search.
+ *
+ * Always returns results (top 5 minimum). Scores determine confidence:
+ * 100 exact name match
+ * 90 exact keyword match
+ * 80 name Levenshtein distance 1
+ * 70 keyword substring or Levenshtein distance 1
+ * 60 substring match on component name (min 4 chars, 50%+ coverage)
+ * 50 description or feature text contains the search term
+ * 40 name Levenshtein distance 2
+ * 30 keyword Levenshtein distance 2
+ * 20 name Levenshtein distance 3
+ *
+ * Each result: { name, score, reason }
+ */
+export async function searchComponents(needle, coreDir, components) {
+ const {pathToFileURL} = await import('node:url');
+ const fs = await import('node:fs');
+ const path = await import('node:path');
+
+ const term = needle.toLowerCase();
+ const allNames = Object.values(components).flat();
+ const scored = new Map();
+
+ function addMatch(name, score, reason) {
+ const existing = scored.get(name);
+ if (!existing || score > existing.score) {
+ scored.set(name, {name, score, reason});
+ }
+ }
+
+ // --- Pass 1: Name matching (sync, fast) ---
+ for (const comp of allNames) {
+ const compLower = comp.toLowerCase();
+
+ // Exact name
+ if (compLower === term) {
+ addMatch(comp, 100, 'exact name');
+ continue;
+ }
+
+ // Substring match on name (both directions)
+ const shorter = term.length < compLower.length ? term : compLower;
+ const longer = term.length < compLower.length ? compLower : term;
+ if (shorter.length >= 4 && longer.includes(shorter)) {
+ const coverage = shorter.length / longer.length;
+ if (coverage >= 0.5) {
+ addMatch(comp, 60, 'name contains "' + shorter + '"');
+ }
+ }
+
+ // Levenshtein on name
+ const dist = levenshteinDistance(term, compLower);
+ if (dist === 1) addMatch(comp, 80, 'similar name (distance ' + dist + ')');
+ else if (dist === 2) addMatch(comp, 40, 'similar name (distance ' + dist + ')');
+ else if (dist === 3) addMatch(comp, 20, 'similar name (distance ' + dist + ')');
+ }
+
+ // --- Pass 2: Keyword + description matching (async, reads doc files) ---
+ for (const comp of allNames) {
+ const srcDir = path.join(coreDir, 'src');
+
+ let docPath = null;
+ const direct = path.join(srcDir, comp, comp + '.doc.mjs');
+ if (fs.existsSync(direct)) {
+ docPath = direct;
+ }
+ if (!docPath) {
+ const xdsDirect = path.join(srcDir, comp, 'XDS' + comp + '.doc.mjs');
+ if (fs.existsSync(xdsDirect)) {
+ docPath = xdsDirect;
+ }
+ }
+ if (!docPath && fs.existsSync(srcDir)) {
+ const entries = fs.readdirSync(srcDir, {withFileTypes: true});
+ for (const entry of entries) {
+ if (!entry.isDirectory()) continue;
+ const nested = path.join(srcDir, entry.name, comp, comp + '.doc.mjs');
+ if (fs.existsSync(nested)) { docPath = nested; break; }
+ }
+ }
+
+ if (!docPath) continue;
+
+ try {
+ const mod = await import(pathToFileURL(docPath).href);
+ const docs = mod.docs;
+ if (!docs) continue;
+
+ // Keyword matching
+ if (docs.keywords && Array.isArray(docs.keywords)) {
+ for (const kw of docs.keywords) {
+ const kwLower = kw.toLowerCase();
+
+ // Exact keyword
+ if (kwLower === term) {
+ addMatch(comp, 90, 'keyword "' + kw + '"');
+ break;
+ }
+
+ // Substring: term contains keyword or keyword contains term
+ const s = term.length < kwLower.length ? term : kwLower;
+ const l = term.length < kwLower.length ? kwLower : term;
+ if (s.length >= 4 && l.includes(s)) {
+ const coverage = s.length / l.length;
+ if (coverage >= 0.5) {
+ addMatch(comp, 70, 'keyword "' + kw + '"');
+ }
+ }
+
+ const dist = levenshteinDistance(term, kwLower);
+ if (dist === 1) addMatch(comp, 70, 'keyword "' + kw + '" (distance ' + dist + ')');
+ else if (dist === 2) addMatch(comp, 30, 'keyword "' + kw + '" (distance ' + dist + ')');
+ }
+ }
+
+ // Description search (whole word boundary)
+ if (docs.description && term.length >= 3) {
+ const descLower = docs.description.toLowerCase();
+ const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+ const re = new RegExp('\\b' + escaped + '\\b');
+ if (re.test(descLower)) {
+ addMatch(comp, 50, 'description mentions "' + term + '"');
+ }
+ }
+
+ // Feature search (whole word boundary)
+ if (docs.features && Array.isArray(docs.features) && term.length >= 3) {
+ for (const feat of docs.features) {
+ const featLower = feat.toLowerCase();
+ const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+ const re = new RegExp('\\b' + escaped + '\\b');
+ if (re.test(featLower)) {
+ addMatch(comp, 50, 'feature mentions "' + term + '"');
+ break;
+ }
+ }
+ }
+ } catch {
+ continue;
+ }
+ }
+
+ const results = Array.from(scored.values())
+ .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+
+ return results;
+}
diff --git a/packages/core/src/AppShell/AppShell.doc.mjs b/packages/core/src/AppShell/AppShell.doc.mjs
index edfaa18e24..d359de4aec 100644
--- a/packages/core/src/AppShell/AppShell.doc.mjs
+++ b/packages/core/src/AppShell/AppShell.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'AppShell',
description:
'Application-level layout shell providing header, side navigation, and main content area — composes XDSLayout internally and replaces the XDSPage + XDSPageLayout pattern.',
+ keywords: ["appshell","layout","scaffold","sidebar","sidenav","topnav","header","navigation","dashboard","shell","page","frame"],
features: [
'Two navigation slots: topNav (horizontal bar) and sideNav (vertical sidebar)',
'Two height modes: fill (viewport-height, independent scroll containers) and auto (page-scroll with sticky nav)',
diff --git a/packages/core/src/AspectRatio/AspectRatio.doc.mjs b/packages/core/src/AspectRatio/AspectRatio.doc.mjs
index fce1ea5244..02caeff26f 100644
--- a/packages/core/src/AspectRatio/AspectRatio.doc.mjs
+++ b/packages/core/src/AspectRatio/AspectRatio.doc.mjs
@@ -3,6 +3,7 @@
export const docs = {
name: 'AspectRatio',
description: 'Maintains a specific aspect ratio for its children.',
+ keywords: ["aspect-ratio","ratio","proportion","responsive","embed","container","widescreen","thumbnail","letterbox","crop"],
features: [
'Accepts any numeric ratio expressed as width/height (e.g. 16/9, 4/3, 1)',
'Children are positioned absolutely to fill the container',
diff --git a/packages/core/src/Avatar/Avatar.doc.mjs b/packages/core/src/Avatar/Avatar.doc.mjs
index c9235ea6df..d33706c6d1 100644
--- a/packages/core/src/Avatar/Avatar.doc.mjs
+++ b/packages/core/src/Avatar/Avatar.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Avatar',
description:
'Avatar component for displaying user profile pictures with fallback support.',
+ keywords: ["avatar","profile","user","photo","thumbnail","initials","gravatar","pfp","userpic"],
features: [
'Image loading: Primary and fallback image sources',
'Initials fallback: Auto-generates initials from user name',
diff --git a/packages/core/src/Badge/Badge.doc.mjs b/packages/core/src/Badge/Badge.doc.mjs
index f895804b65..a2066e70ea 100644
--- a/packages/core/src/Badge/Badge.doc.mjs
+++ b/packages/core/src/Badge/Badge.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Badge',
description:
'A badge component for displaying status indicators, counts, or labels.',
+ keywords: ["badge","tag","chip","label","status","indicator","dot","count","counter","pill","notification","marker"],
props: [
{
name: 'variant',
diff --git a/packages/core/src/Banner/Banner.doc.mjs b/packages/core/src/Banner/Banner.doc.mjs
index 96af3a5f57..3d7836a9e2 100644
--- a/packages/core/src/Banner/Banner.doc.mjs
+++ b/packages/core/src/Banner/Banner.doc.mjs
@@ -5,6 +5,7 @@ export const docs = {
description:
'Persistent status notification for info, warning, error, or success messages.',
+ keywords: ["banner","alert","notification","callout","notice","status","message","info","warning","error","success","toast"],
features: [
'Two-part layout: colored status header with icon, title, description, action buttons, and optional dismiss; optional card-background content area below',
'When no children are provided, only the colored header renders',
diff --git a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
index a774e61fb3..cbc3435a18 100644
--- a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
+++ b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
@@ -3,6 +3,7 @@
export const docs = {
name: 'Breadcrumbs',
description: 'A navigation breadcrumb trail with semantic HTML.',
+ keywords: ["breadcrumbs","breadcrumb","navigation","nav","crumbs","trail","path","hierarchy","wayfinding","steps"],
features: [
'Renders a <nav> landmark with an ordered list of breadcrumb items',
'Configurable separator between items (defaults to /)',
diff --git a/packages/core/src/Button/Button.doc.mjs b/packages/core/src/Button/Button.doc.mjs
index 560cd42e5c..56515eac7b 100644
--- a/packages/core/src/Button/Button.doc.mjs
+++ b/packages/core/src/Button/Button.doc.mjs
@@ -5,6 +5,7 @@ export const docs = {
description:
'XDSButton component with multiple variants, sizes, and isLoading state support.',
+ keywords: ["button","btn","cta","submit","action","loading","primary","secondary","ghost","destructive","danger"],
features: [
"Variants: 'primary', 'secondary', 'ghost', 'destructive'",
'Sizes: sm (28px), md (32px), lg (36px)',
diff --git a/packages/core/src/Calendar/Calendar.doc.mjs b/packages/core/src/Calendar/Calendar.doc.mjs
index 4ddcc73816..98f456391f 100644
--- a/packages/core/src/Calendar/Calendar.doc.mjs
+++ b/packages/core/src/Calendar/Calendar.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Calendar',
description:
'XDSCalendar component for date selection with single and range modes.',
+ keywords: ["calendar","datepicker","date picker","rangepicker","date range","monthview","daypicker"],
features: [
"Selection Modes: 'single' (default) and 'range'",
'Multi-Month Display: Show 1 or 2 months side by side',
diff --git a/packages/core/src/Card/Card.doc.mjs b/packages/core/src/Card/Card.doc.mjs
index ad3ac6db41..9888aa73ce 100644
--- a/packages/core/src/Card/Card.doc.mjs
+++ b/packages/core/src/Card/Card.doc.mjs
@@ -3,6 +3,7 @@
export const docs = {
name: 'Card',
description: 'Card container component with shadow and themed styling.',
+ keywords: ["card","surface","panel","container","elevated","shadow","box","paper","tile","well"],
features: [
'Top-level container for elevated content',
'Provides card-specific appearance: background, shadow, and border-radius',
diff --git a/packages/core/src/Center/Center.doc.mjs b/packages/core/src/Center/Center.doc.mjs
index b7141ebeb7..cb175a47aa 100644
--- a/packages/core/src/Center/Center.doc.mjs
+++ b/packages/core/src/Center/Center.doc.mjs
@@ -3,6 +3,7 @@
export const docs = {
name: 'Center',
description: 'Centers children horizontally and/or vertically using flexbox.',
+ keywords: ["center","centered","centering","align","alignment","justify","flexbox","middle"],
features: [
'Supports centering on both axes, horizontal only, or vertical only',
'Inline-flex mode for centering inline content such as text and icons',
diff --git a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
index 75897cd22f..4e0580e345 100644
--- a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
+++ b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
@@ -3,6 +3,7 @@
export const docs = {
name: 'CheckboxInput',
description: 'A checkbox input component for toggling boolean values.',
+ keywords: ["checkbox","check","toggle","tick","indeterminate","boolean","tristate"],
features: [
'Accessible — always includes a label (can be visually hidden)',
'Indeterminate state — supports indeterminate for "select all" patterns',
diff --git a/packages/core/src/Collapsible/Collapsible.doc.mjs b/packages/core/src/Collapsible/Collapsible.doc.mjs
index 7a7d84085d..58852135f4 100644
--- a/packages/core/src/Collapsible/Collapsible.doc.mjs
+++ b/packages/core/src/Collapsible/Collapsible.doc.mjs
@@ -3,6 +3,7 @@
export const docs = {
name: 'Collapsible',
description: 'Collapsible content primitive and group coordination.',
+ keywords: ["accordion","collapse","expandable","disclosure","toggle","panel","foldable","expander","expand"],
features: [
'XDSCollapsible makes any content collapsible — a trigger toggles visibility of the content area',
'Handles state management, accessibility (aria-expanded, keyboard activation), and a chevron indicator',
diff --git a/packages/core/src/DateInput/DateInput.doc.mjs b/packages/core/src/DateInput/DateInput.doc.mjs
index b97d8bf8d7..6922831b17 100644
--- a/packages/core/src/DateInput/DateInput.doc.mjs
+++ b/packages/core/src/DateInput/DateInput.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'DateInput',
description:
'XDSDateInput component combining a text input with a calendar popover for date selection.',
+ keywords: ["dateinput","datepicker","datefield","calendar","dateselect","dateentry","datechooser"],
features: [
'Text Input — manual date entry with flexible parsing (supports various formats)',
'Calendar Popover — click icon or use keyboard to open calendar picker',
diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjs
index 6e4838944f..2400214d23 100644
--- a/packages/core/src/Dialog/Dialog.doc.mjs
+++ b/packages/core/src/Dialog/Dialog.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Dialog',
description:
'Modal dialog using the native <dialog> element with automatic focus trapping, backdrop, and purpose-based dismissal control.',
+ keywords: ["dialog","modal","popup","overlay","lightbox","alert","confirm","prompt","backdrop","focus trap"],
features: [
"Native <dialog>: Uses the browser's built-in modal behavior via showModal()",
'Automatic focus trap: Focus is trapped within the dialog when open (browser-native)',
diff --git a/packages/core/src/Divider/Divider.doc.mjs b/packages/core/src/Divider/Divider.doc.mjs
index 50836d0653..a15892c2b5 100644
--- a/packages/core/src/Divider/Divider.doc.mjs
+++ b/packages/core/src/Divider/Divider.doc.mjs
@@ -5,6 +5,7 @@
export const docs = {
name: 'Divider',
description: 'Visual separator with optional label, using XDS design tokens.',
+ keywords: ["divider","separator","hr","rule","line","border","spacer","horizontal rule"],
features: [
'Supports horizontal and vertical orientations',
'Optional label centered on the divider line',
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
index b34122dd5e..e53e3e9cd3 100644
--- a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
+++ b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'DropdownMenu',
description:
'A dropdown menu component for displaying actionable items in a popup menu.',
+ keywords: ["dropdown","menu","popover","select","actions","contextmenu","overflow","kebab","menubutton"],
features: [
'Button customization: Customize the trigger button via the `button` prop (supports all XDSButton props)',
'Data-driven items: Pass items via the `items` prop with support for sections and dividers',
diff --git a/packages/core/src/EmptyState/EmptyState.doc.mjs b/packages/core/src/EmptyState/EmptyState.doc.mjs
index f3d5d10b7e..50b7e7f0c4 100644
--- a/packages/core/src/EmptyState/EmptyState.doc.mjs
+++ b/packages/core/src/EmptyState/EmptyState.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'EmptyState',
description:
'An empty state placeholder for content areas with no data. Displays an icon or illustration, title, optional description, and action buttons.',
+ keywords: ["emptystate","empty","placeholder","nodata","blank","noresults","illustration","blankslate"],
features: [
'Uses role="status" so screen readers announce the empty state automatically',
'Icon slot renders as decorative (aria-hidden="true") — no extra labeling needed',
diff --git a/packages/core/src/Field/Field.doc.mjs b/packages/core/src/Field/Field.doc.mjs
index 4083a5526d..818b672ec8 100644
--- a/packages/core/src/Field/Field.doc.mjs
+++ b/packages/core/src/Field/Field.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Field',
description:
'A form field wrapper component that provides label, description, and optional/required indicators.',
+ keywords: ["field","formfield","formgroup","formcontrol","label","input","required","optional","helpertext","hint"],
features: [
'Label Support — required label for accessibility (can be visually hidden)',
'Description — optional description text displayed between the label and input',
diff --git a/packages/core/src/FormLayout/FormLayout.doc.mjs b/packages/core/src/FormLayout/FormLayout.doc.mjs
index a711e09573..b5247abbd3 100644
--- a/packages/core/src/FormLayout/FormLayout.doc.mjs
+++ b/packages/core/src/FormLayout/FormLayout.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'FormLayout',
description:
'A spatial layout container for arranging form fields with consistent spacing and direction.',
+ keywords: ["formlayout","form","fieldset","formgroup","formcontainer","fields","vertical","horizontal"],
props: [
{
name: 'direction',
diff --git a/packages/core/src/Grid/Grid.doc.mjs b/packages/core/src/Grid/Grid.doc.mjs
index e4d85008fc..b216758ad3 100644
--- a/packages/core/src/Grid/Grid.doc.mjs
+++ b/packages/core/src/Grid/Grid.doc.mjs
@@ -3,6 +3,7 @@
export const docs = {
name: 'Grid',
description: 'CSS Grid-based layout with responsive auto-fit support.',
+ keywords: ["grid","columns","responsive","auto-fit","masonry","tiles","row","col","simplegrid"],
features: [
'Fixed-column grids via the `columns` prop',
'Responsive auto-fit columns via `minChildWidth` — items wrap based on available space',
diff --git a/packages/core/src/HoverCard/HoverCard.doc.mjs b/packages/core/src/HoverCard/HoverCard.doc.mjs
index 8b8289446a..b4ce576a13 100644
--- a/packages/core/src/HoverCard/HoverCard.doc.mjs
+++ b/packages/core/src/HoverCard/HoverCard.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'HoverCard',
description:
'A hover/focus triggered overlay for displaying rich, interactive content anchored to a trigger element.',
+ keywords: ["hovercard","hover card","popover","tooltip","preview card","flyout","overlay","hover popup"],
features: [
'CSS Anchor Positioning for automatic placement relative to trigger elements',
'Popover API for top-layer rendering — no React portals needed',
diff --git a/packages/core/src/Icon/Icon.doc.mjs b/packages/core/src/Icon/Icon.doc.mjs
index 9740c7fc5a..bc9c714430 100644
--- a/packages/core/src/Icon/Icon.doc.mjs
+++ b/packages/core/src/Icon/Icon.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Icon',
description:
'Renders icons with XDS design system colors and sizes. Supports both direct SVG icon components and semantic icon names that adapt to the active theme.',
+ keywords: ["icon","svg","glyph","symbol","pictogram","graphic","vector"],
features: [
"Semantic Icon Names: Use names like 'close' or 'chevronDown' — resolved from the theme's icon registry",
'Direct Icon Components: Pass any SVG icon component (heroicons, lucide, etc.) directly',
diff --git a/packages/core/src/Kbd/Kbd.doc.mjs b/packages/core/src/Kbd/Kbd.doc.mjs
index a09c0a9bff..c4b84251b2 100644
--- a/packages/core/src/Kbd/Kbd.doc.mjs
+++ b/packages/core/src/Kbd/Kbd.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Kbd',
description:
'Displays a keyboard shortcut as styled <kbd> elements. Use in tooltips, menus, and documentation to show key combinations.',
+ keywords: ["kbd","keyboard","shortcut","hotkey","keybinding","keystroke","keycombo","modifier","accelerator"],
features: [
'Key parsing — splits "mod+k" into individual styled <kbd> elements',
'Modifier symbols — maps mod/ctrl/alt/shift/enter/backspace/escape/arrows to platform symbols',
diff --git a/packages/core/src/Layer/Layer.doc.mjs b/packages/core/src/Layer/Layer.doc.mjs
index ec6f1bab63..76a11dee43 100644
--- a/packages/core/src/Layer/Layer.doc.mjs
+++ b/packages/core/src/Layer/Layer.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Layer',
description:
'Core hook for overlay positioning using CSS Anchor Positioning and the Popover API — no React portals needed. Popover, HoverCard, and Tooltip build on this foundation and live in their own directories.',
+ keywords: ["layer","overlay","popover","positioning","anchor","floating","dropdown","popper","popup","portal"],
features: [
'CSS Anchor Positioning for automatic placement relative to trigger elements',
'Popover API for top-layer rendering — no React portals needed',
diff --git a/packages/core/src/Layout/Layout.doc.mjs b/packages/core/src/Layout/Layout.doc.mjs
index 7a4717ab9f..e80e7a0069 100644
--- a/packages/core/src/Layout/Layout.doc.mjs
+++ b/packages/core/src/Layout/Layout.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Layout',
description:
'Composable utilities and components for building structured layouts with a container/content separation pattern.',
+ keywords: ["layout","container","content","flex","box","wrapper","scaffold","page","shell"],
features: [
'Primitive + higher-order architecture — XDSLayoutContainer is a primitive; XDSCard, XDSSection are higher-order',
'Directional padding via CSS variables — inner/outer, horizontal/vertical padding control',
diff --git a/packages/core/src/Link/Link.doc.mjs b/packages/core/src/Link/Link.doc.mjs
index 851b9c371a..2b7430e689 100644
--- a/packages/core/src/Link/Link.doc.mjs
+++ b/packages/core/src/Link/Link.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Link',
description:
'XDSLink component for styled anchor links with multiple variants and features, plus polymorphic link infrastructure for rendering custom link components (Next.js Link, React Router Link, etc.).',
+ keywords: ["link","anchor","href","hyperlink","navigation","url","external","textlink"],
features: [
"Color control: Uses XDSText color prop ('active' default, 'secondary', 'inherit', etc.)",
'External links: Opens in new tab with external link icon',
diff --git a/packages/core/src/List/List.doc.mjs b/packages/core/src/List/List.doc.mjs
index e501667f28..4a4cf40438 100644
--- a/packages/core/src/List/List.doc.mjs
+++ b/packages/core/src/List/List.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'List',
description:
'Vertical list component for rendering collections of items with consistent spacing, dividers, and marker styles. Uses a composition model: XDSList wraps XDSListItem sub-components.',
+ keywords: ["list","listitem","listbox","menu","collection","items","ul","navlist"],
features: [
'Composition model — XDSList wraps XDSListItem sub-components',
'Density variants: compact, balanced, spacious',
diff --git a/packages/core/src/MetadataList/MetadataList.doc.mjs b/packages/core/src/MetadataList/MetadataList.doc.mjs
index 80e476d540..5f3b806278 100644
--- a/packages/core/src/MetadataList/MetadataList.doc.mjs
+++ b/packages/core/src/MetadataList/MetadataList.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'MetadataList',
description:
'A read-only labeled list for displaying key-value metadata. Semantic equivalent of HTML <dl>/<dt>/<dd> with layout control, column modes, and consistent styling. Uses a composition model: XDSMetadataList wraps XDSMetadataListItem sub-components.',
+ keywords: ["metadata","description","definition","keyvalue","properties","details","attributes","summary"],
features: [
'Composition model — XDSMetadataList wraps XDSMetadataListItem sub-components',
'Column modes: single, multi (auto-fill), or fixed number',
diff --git a/packages/core/src/MobileNav/MobileNav.doc.mjs b/packages/core/src/MobileNav/MobileNav.doc.mjs
index 8547d9a39f..c2760ee9b3 100644
--- a/packages/core/src/MobileNav/MobileNav.doc.mjs
+++ b/packages/core/src/MobileNav/MobileNav.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'MobileNav',
description:
'Slide-out drawer overlay for mobile navigation. The mobile counterpart to XDSSideNav — accepts the same children (XDSSideNavSection, XDSSideNavItem, or any ReactNode).',
+ keywords: ["mobilenav","drawer","sidebar","navigation","hamburger","menu","offcanvas","slideout","navdrawer"],
props: [
{
name: 'isOpen',
diff --git a/packages/core/src/MoreMenu/MoreMenu.doc.mjs b/packages/core/src/MoreMenu/MoreMenu.doc.mjs
index 1de71c7fb0..8d227d8f4f 100644
--- a/packages/core/src/MoreMenu/MoreMenu.doc.mjs
+++ b/packages/core/src/MoreMenu/MoreMenu.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'MoreMenu',
description:
'Overflow menu with a three-dot icon trigger. A convenience wrapper that composes an icon-only XDSButton with a dropdown menu, eliminating the boilerplate of wiring up state management, positioning, and accessibility attributes.',
+ keywords: ["moremenu","overflow","kebab","dotmenu","threedot","ellipsis","dropdown","contextmenu","actionmenu"],
props: [
{
name: 'items',
diff --git a/packages/core/src/NavIcon/NavIcon.doc.mjs b/packages/core/src/NavIcon/NavIcon.doc.mjs
index e1d9c13f3a..094821557f 100644
--- a/packages/core/src/NavIcon/NavIcon.doc.mjs
+++ b/packages/core/src/NavIcon/NavIcon.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'NavIcon',
description:
'Circular icon container with accent background for navigation headers.',
+ keywords: ["navicon","iconbutton","toolbar icon","appbar icon","nav button"],
features: [
'Shared — used in both XDSTopNavHeading and XDSPageNavHeader',
'Accent background — uses --color-accent with --color-on-accent contrast',
diff --git a/packages/core/src/NumberInput/NumberInput.doc.mjs b/packages/core/src/NumberInput/NumberInput.doc.mjs
index 3944a84de7..304ddfd4e6 100644
--- a/packages/core/src/NumberInput/NumberInput.doc.mjs
+++ b/packages/core/src/NumberInput/NumberInput.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'NumberInput',
description:
'A number input component for collecting numeric user input with validation.',
+ keywords: ["numberinput","numberfield","stepper","spinner","counter","increment","decrement","quantity","numberpicker"],
features: [
'Label Support — required label for accessibility (can be visually hidden)',
'Description — optional description text displayed between the label and input',
diff --git a/packages/core/src/Pagination/Pagination.doc.mjs b/packages/core/src/Pagination/Pagination.doc.mjs
index 5d1bd14cd8..c6b85570a8 100644
--- a/packages/core/src/Pagination/Pagination.doc.mjs
+++ b/packages/core/src/Pagination/Pagination.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Pagination',
description:
'Standalone pagination controls for navigating through pages of content. Supports multiple display variants and works with known totals or cursor-based pagination.',
+ keywords: ["pagination","pager","paginator","pagenavigation","paging","paginate","pages","pagecontrol"],
props: [
{
name: 'page',
diff --git a/packages/core/src/Popover/Popover.doc.mjs b/packages/core/src/Popover/Popover.doc.mjs
index 8affe124d2..49612fec49 100644
--- a/packages/core/src/Popover/Popover.doc.mjs
+++ b/packages/core/src/Popover/Popover.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Popover',
description:
'A click-triggered popover for displaying interactive content anchored to a trigger element, implementing the button + dialog ARIA pattern.',
+ keywords: ["popover","popup","dropdown","tooltip","overlay","flyout","callout","popper","anchor","floating","bubble"],
features: [
'CSS Anchor Positioning for automatic placement relative to trigger elements',
'Popover API for top-layer rendering — no React portals needed',
diff --git a/packages/core/src/PowerSearch/PowerSearch.doc.mjs b/packages/core/src/PowerSearch/PowerSearch.doc.mjs
index 68338be634..02d254a315 100644
--- a/packages/core/src/PowerSearch/PowerSearch.doc.mjs
+++ b/packages/core/src/PowerSearch/PowerSearch.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'PowerSearch',
description:
'Structured filter bar where each token represents a filter (field + operator + value). Users select fields from a typeahead dropdown, configure operators and values in an edit popover, and manage filters as removable tokens.',
+ keywords: ["powersearch","search","searchbar","filter","filterbar","faceted","querybuilder","structured","omnibar"],
props: [
{
name: 'config',
diff --git a/packages/core/src/ProgressBar/ProgressBar.doc.mjs b/packages/core/src/ProgressBar/ProgressBar.doc.mjs
index 25bce5785b..bd034d64c7 100644
--- a/packages/core/src/ProgressBar/ProgressBar.doc.mjs
+++ b/packages/core/src/ProgressBar/ProgressBar.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'ProgressBar',
description:
'A progress bar for displaying determinate or indeterminate progress.',
+ keywords: ["progressbar","progress","loader","loading","linear","determinate","indeterminate","meter"],
features: [
'Determinate mode uses role="meter" with aria-valuenow, aria-valuemin, and aria-valuemax',
'Indeterminate mode uses role="progressbar" without value attributes',
diff --git a/packages/core/src/RadioList/RadioList.doc.mjs b/packages/core/src/RadioList/RadioList.doc.mjs
index 4ea22ca511..786058f24e 100644
--- a/packages/core/src/RadioList/RadioList.doc.mjs
+++ b/packages/core/src/RadioList/RadioList.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'RadioList',
description:
'A radio group component for single-value selection from a list of options.',
+ keywords: ["radiolist","radio","radiogroup","radiobutton","optionlist","singlechoice","choicelist"],
features: [
'Accessible — uses native <input type="radio"> with proper role="radiogroup" and ARIA attributes',
'Orientation — supports vertical and horizontal layouts',
diff --git a/packages/core/src/Section/Section.doc.mjs b/packages/core/src/Section/Section.doc.mjs
index ee0ea24ac4..9966cb650f 100644
--- a/packages/core/src/Section/Section.doc.mjs
+++ b/packages/core/src/Section/Section.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Section',
description:
'Container with background variants for creating visually distinct regions that automatically escape parent container padding for edge-to-edge fills.',
+ keywords: ["section","panel","container","group","fieldset","region","block"],
features: [
'Background variants: section, transparent, and wash',
'Automatically escapes parent container padding for edge-to-edge fills',
diff --git a/packages/core/src/Selector/Selector.doc.mjs b/packages/core/src/Selector/Selector.doc.mjs
index d03f09fa3c..89cfe99246 100644
--- a/packages/core/src/Selector/Selector.doc.mjs
+++ b/packages/core/src/Selector/Selector.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Selector',
description:
'Dropdown selector for choosing from a list of options. Follows XDS input conventions with label, status, and field props.',
+ keywords: ["selector","select","dropdown","combobox","picker","listbox","chooser","autocomplete","option","selectmenu"],
features: [
'Supports string items (auto-converted to {value, label}), object items with optional icon and disabled state, dividers, and labeled sections',
'Custom item rendering via children render prop and XDSSelectorItem helper',
diff --git a/packages/core/src/SideNav/SideNav.doc.mjs b/packages/core/src/SideNav/SideNav.doc.mjs
index 6c47991c51..64d6117b01 100644
--- a/packages/core/src/SideNav/SideNav.doc.mjs
+++ b/packages/core/src/SideNav/SideNav.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'SideNav',
description:
'Sidebar navigation component for application pages. Supports sections, nested items, selected state, icons, and collapsible sidebar.',
+ keywords: ["sidenav","sidebar","navigation","drawer","menu","nav","aside","sidemenu","navmenu","sider","treeview"],
features: [
'Five-zone layout: header, topContent, children (scrollable), footer, footerIcons',
'Smart header interaction boundary logic — links and menu trigger coexist without overlap',
diff --git a/packages/core/src/Skeleton/Skeleton.doc.mjs b/packages/core/src/Skeleton/Skeleton.doc.mjs
index 3ec154641f..ddc3473f40 100644
--- a/packages/core/src/Skeleton/Skeleton.doc.mjs
+++ b/packages/core/src/Skeleton/Skeleton.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Skeleton',
description:
'A placeholder loading component that displays an animated pulsing effect while content is loading.',
+ keywords: ["skeleton","placeholder","loading","shimmer","pulse","loader","bone","ghost","preloader"],
features: [
'Pulsing Animation: Smooth opacity animation using stepped timing for a subtle shimmer effect',
'Staggered Animation: Sequential skeletons can be staggered to create a wave effect',
diff --git a/packages/core/src/Slider/Slider.doc.mjs b/packages/core/src/Slider/Slider.doc.mjs
index be2eb4b3fb..c220829e26 100644
--- a/packages/core/src/Slider/Slider.doc.mjs
+++ b/packages/core/src/Slider/Slider.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Slider',
description:
'A slider component for selecting numeric values or ranges with full keyboard and pointer support.',
+ keywords: ["slider","range","slidebar","trackbar","scrubber","knob","thumb","rangeslider"],
features: [
'Single & range modes: Pass a `number` for single thumb, `[number, number]` for range',
'Orientation: Supports `horizontal` and `vertical` layouts',
diff --git a/packages/core/src/Spinner/Spinner.doc.mjs b/packages/core/src/Spinner/Spinner.doc.mjs
index 22e47406ae..7c8374d2ac 100644
--- a/packages/core/src/Spinner/Spinner.doc.mjs
+++ b/packages/core/src/Spinner/Spinner.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Spinner',
description:
'An animated loading indicator with optional visible label.',
+ keywords: ["spinner","loader","loading","circular","progress","spin","activity","busy","indeterminate"],
features: [
'Canvas Animation: Lightweight canvas-based spinner with smooth 360° rotation',
'Size Variants: Three sizes (sm, md, lg) matching existing inline spinners',
diff --git a/packages/core/src/Stack/Stack.doc.mjs b/packages/core/src/Stack/Stack.doc.mjs
index 3fe016be32..fa9e33bb0b 100644
--- a/packages/core/src/Stack/Stack.doc.mjs
+++ b/packages/core/src/Stack/Stack.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Stack',
description:
'Stack layout primitives for arranging items in horizontal or vertical sequences using flexbox-based layout with themed spacing tokens.',
+ keywords: ["stack","hstack","vstack","flexbox","flex","spacing","gap","horizontal","vertical","row","column"],
features: [
'Horizontal (XDSHStack) and vertical (XDSVStack) stacking',
'Themed spacing via gap tokens from the design system spacing scale',
diff --git a/packages/core/src/StatusDot/StatusDot.doc.mjs b/packages/core/src/StatusDot/StatusDot.doc.mjs
index 535e8ca0e2..6d9d3b0e81 100644
--- a/packages/core/src/StatusDot/StatusDot.doc.mjs
+++ b/packages/core/src/StatusDot/StatusDot.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'StatusDot',
description:
'A small colored dot indicator for status display (online/offline, severity, etc).',
+ keywords: ["statusdot","dot","indicator","status","signal","presence","availability","online","pip"],
features: [
'Five semantic color variants: positive, warning, negative, info, neutral',
'Single size: 8px',
diff --git a/packages/core/src/Switch/Switch.doc.mjs b/packages/core/src/Switch/Switch.doc.mjs
index eaef44d004..7b75d0a25b 100644
--- a/packages/core/src/Switch/Switch.doc.mjs
+++ b/packages/core/src/Switch/Switch.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Switch',
description:
'A toggle switch component for boolean values with integrated label support.',
+ keywords: ["switch","toggle","onoff","flipswitch","boolean","toggleswitch"],
features: [
'Boolean toggle — fixed 40x24px track with animated 16px (off) / 20px (on) thumb',
'Label integration — uses XDSFieldLabel for accessible labels with optional tooltip and icon',
diff --git a/packages/core/src/TabList/TabList.doc.mjs b/packages/core/src/TabList/TabList.doc.mjs
index 17d50991dd..8adc8fbdff 100644
--- a/packages/core/src/TabList/TabList.doc.mjs
+++ b/packages/core/src/TabList/TabList.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'TabList',
description:
'Tab navigation components with overflow menu support, rendering as a semantic nav landmark with button or anchor tab items.',
+ keywords: ["tabs","tabbar","tabstrip","navigation","tabpanel","tabgroup","segmented","navtabs","tab"],
features: [
'Context-based communication: XDSTabListContext passes value/onChange/size from XDSTabList to children',
'Single-responsibility XDSTab: renders as <button> or <a> (when href is provided) in the nav',
diff --git a/packages/core/src/Table/Table.doc.mjs b/packages/core/src/Table/Table.doc.mjs
index 30198bde2b..7f49fdaccf 100644
--- a/packages/core/src/Table/Table.doc.mjs
+++ b/packages/core/src/Table/Table.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Table',
description:
'Data-driven table with rich cell content via renderCell. Compose cells with XDSBadge, XDSStatusDot, XDSText, XDSAvatar, and layout primitives. XDSBaseTable provides the unstyled structural core with a composable plugin pipeline.',
+ keywords: ["table","datatable","datagrid","spreadsheet","sorting","virtualized","columns","rows","selection","pinning"],
features: [
'Data-driven rendering — pass data + columns, rows render automatically',
'Rich cell content via renderCell — compose XDS components (XDSBadge, XDSStatusDot, XDSText, XDSAvatar) inside table cells',
diff --git a/packages/core/src/Text/Text.doc.mjs b/packages/core/src/Text/Text.doc.mjs
index 5f09a0161c..b1191614bf 100644
--- a/packages/core/src/Text/Text.doc.mjs
+++ b/packages/core/src/Text/Text.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Text',
description:
'Typography components for the XDS design system, including semantic body text, headings, and a wrapper for applying typography styles to native HTML.',
+ keywords: ["text","typography","label","paragraph","heading","caption","font","body","subtitle"],
examples: [
{
label: 'Body text',
diff --git a/packages/core/src/TextArea/TextArea.doc.mjs b/packages/core/src/TextArea/TextArea.doc.mjs
index f548aa5efb..b2fb29439b 100644
--- a/packages/core/src/TextArea/TextArea.doc.mjs
+++ b/packages/core/src/TextArea/TextArea.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'TextArea',
description:
'A multi-line text input component for collecting longer user input.',
+ keywords: ["textarea","textfield","multiline","comment","message","autoresize","autosize","charlimit"],
features: [
'Label support — required label for accessibility, can be visually hidden',
'Description — optional text displayed between the label and textarea',
diff --git a/packages/core/src/TextInput/TextInput.doc.mjs b/packages/core/src/TextInput/TextInput.doc.mjs
index 6f1aa9b50a..93eaa95d54 100644
--- a/packages/core/src/TextInput/TextInput.doc.mjs
+++ b/packages/core/src/TextInput/TextInput.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'TextInput',
description:
'A text input component for collecting user text input, with label, description, validation status, and optional/required indicators.',
+ keywords: ["textinput","textfield","input","search","clearable","prefix","suffix","adornment","validation"],
features: [
'Label support — required label for accessibility (can be visually hidden)',
'Description — optional text displayed between the label and input',
diff --git a/packages/core/src/TimeInput/TimeInput.doc.mjs b/packages/core/src/TimeInput/TimeInput.doc.mjs
index e1530e8c64..59eac240a8 100644
--- a/packages/core/src/TimeInput/TimeInput.doc.mjs
+++ b/packages/core/src/TimeInput/TimeInput.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'TimeInput',
description:
'Time input with free-text entry, text parsing, and arrow-key navigation.',
+ keywords: ["timeinput","timepicker","time","clock","hour","minute","ampm","timeselect","timefield"],
features: [
'Accepts free-text time entry and parses common formats (e.g. "2:30 PM", "14:30")',
'Supports 12-hour and 24-hour display formats',
diff --git a/packages/core/src/Token/Token.doc.mjs b/packages/core/src/Token/Token.doc.mjs
index 42c118d53d..6e009d882d 100644
--- a/packages/core/src/Token/Token.doc.mjs
+++ b/packages/core/src/Token/Token.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Token',
description:
'A chip/tag component for displaying entities inline. Renders as a <span> by default, <a> when href is provided, or a <span> with an invisible <button> inside when onClick is provided.',
+ keywords: ["token","chip","tag","pill","label","removable","dismissible","filter chip","closable"],
features: [
'Polymorphic — renders as <span>, <a>, or interactive <span>+<button> based on props',
'Invisible button pattern for onClick preserves real button semantics while allowing focus-within outline on the full token',
diff --git a/packages/core/src/Tokenizer/Tokenizer.doc.mjs b/packages/core/src/Tokenizer/Tokenizer.doc.mjs
index 5cd7355856..6d63b885bb 100644
--- a/packages/core/src/Tokenizer/Tokenizer.doc.mjs
+++ b/packages/core/src/Tokenizer/Tokenizer.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Tokenizer',
description:
'Multi-select typeahead with token chips for selected items. Composes XDSBaseTypeahead for search and XDSToken for chips.',
+ keywords: ["tokenizer","multiselect","multi-select","chips","tags","combobox","autocomplete","taginput","chipinput"],
props: [
{
name: 'label',
diff --git a/packages/core/src/Tooltip/Tooltip.doc.mjs b/packages/core/src/Tooltip/Tooltip.doc.mjs
index 84a3cb5153..b1bd9d9e10 100644
--- a/packages/core/src/Tooltip/Tooltip.doc.mjs
+++ b/packages/core/src/Tooltip/Tooltip.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Tooltip',
description:
'A hover/focus triggered tooltip for displaying short, non-interactive text anchored to a trigger element.',
+ keywords: ["tooltip","hint","infotip","title","hover","flyout","balloon","helpertext"],
features: [
'CSS Anchor Positioning for automatic placement relative to trigger elements',
'Popover API for top-layer rendering — no React portals needed',
diff --git a/packages/core/src/TopNav/TopNav.doc.mjs b/packages/core/src/TopNav/TopNav.doc.mjs
index a97435988b..b172e1ab15 100644
--- a/packages/core/src/TopNav/TopNav.doc.mjs
+++ b/packages/core/src/TopNav/TopNav.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'TopNav',
description:
'Top navigation bar component for application headers with slot-based layout and companion nav item components.',
+ keywords: ["topnav","navbar","appbar","header","toolbar","navigation","menubar","topbar"],
features: [
'Slot-based layout — heading, startContent, centerContent, and endContent slots for flexible organization',
'Three-column centering — when centerContent is provided, switches to CSS grid (1fr auto 1fr) for true horizontal centering',
diff --git a/packages/core/src/Typeahead/Typeahead.doc.mjs b/packages/core/src/Typeahead/Typeahead.doc.mjs
index 67f9de16b3..beb3f0c624 100644
--- a/packages/core/src/Typeahead/Typeahead.doc.mjs
+++ b/packages/core/src/Typeahead/Typeahead.doc.mjs
@@ -4,6 +4,7 @@ export const docs = {
name: 'Typeahead',
description:
'Searchable dropdown components for single-item selection with keyboard navigation. Supports async and sync search via a searchSource interface.',
+ keywords: ["typeahead","autocomplete","combobox","searchbox","autosuggest","select","dropdown","lookup","searchable","suggestion","picker"],
features: [
'Async and sync search via a searchSource interface with search() and bootstrap() methods',
'Bootstrap results shown on focus before typing (via hasEntriesOnFocus)',
diff --git a/packages/core/src/docs-types.ts b/packages/core/src/docs-types.ts
index f8ab5117b4..4dc85adafd 100644
--- a/packages/core/src/docs-types.ts
+++ b/packages/core/src/docs-types.ts
@@ -180,6 +180,12 @@ interface BaseDoc {
* Start with the most common usage pattern, then progress to advanced.
* Include 2-5 examples (complex components may justify more). */
examples: Example[];
+ /** Search keywords for CLI discovery. Terms a developer might type when
+ * looking for this component: synonyms, related UI concepts, and common
+ * names from other design systems (MUI, Chakra, Radix, shadcn).
+ * Lowercase only. Used by `xds component <term>` for fuzzy matching.
+ * e.g. `['accordion', 'expand', 'toggle', 'disclosure']` for Collapsible */
+ keywords?: string[];
/** Key capabilities as short bullet points. Each string is one feature.
* Strongly recommended even though optional — all existing components
* include this field. Use "Category: details" format.