feat(cli): index component usage guidance, one tier below description - #5937
Open
josephfarina wants to merge 1 commit into
Open
feat(cli): index component usage guidance, one tier below description#5937josephfarina wants to merge 1 commit into
josephfarina wants to merge 1 commit into
Conversation
97 core components ship best-practice guidance and none of it was searchable. Banner describes itself as "a persistent message"; only its guidance says caution, problems, form errors. Measured on the real registry, `caution`, `problems`, `sources` and `attention` each now return the component whose guidance defines them, and each returned nothing relevant before. Guidance scores 45, below description's 50, so a component that IS the answer outranks one whose advice merely mentions the term. It sits below MIN_TOKEN_SCORE deliberately, so it never counts as a matched concept in a multi-word query. Letting it count was measured moving `nested menu` from SideNav to List and `explain why a field is required` from Field to TextInput. With the floor at 50, a 28-query sweep shows zero top-result changes and zero regressions, and the single-word gains are kept.
josephfarina
requested review from
cixzhang and
imdreamrunner
as code owners
September 2, 2026 21:51
meta-cla
Bot
added
the
CLA Signed
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
josephfarina
added a commit
that referenced
this pull request
Sep 2, 2026
Review asked for the guidance indexing and the thin-kit hint as separate small PRs. The hint is now #5938 and the guidance tier is #5937, so this branch keeps only the coverage gate on the build pages group and the matchedTerms/queryTerms plumbing that gate needs. No behaviour change to the gate itself.
Contributor
PR Analysis Report📚 Storybook PreviewView Storybook for this PR 🧪 Sandbox PreviewView Sandbox for this PR No new or modified components detected. Bundle Size SummaryNo component packages changed. Accessibility AuditStatus: No accessibility violations detected. Generated by PR Enrichment workflow | Storybook | Sandbox | View full report |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Split out of #5320 at review request: the guidance indexing, on its own, with red→green evidence.
The gap
97 core components ship best-practice guidance and none of it was searchable.
Bannerdescribes itself as "a persistent message"; only its guidance says caution, problems, form errors. The reader's vocabulary lives in guidance, and search never read it.Red → green, on the real registry
Each term appears only in that component's guidance — not its name, keywords, or description.
cautionproblemssourcesattentionWhy 45, and why below the token floor
Guidance scores 45, under description's 50, so a component that is the answer outranks one whose advice merely mentions the term — the ordering that put
ToastbehindCard,DialogandItemon "notification".It also sits deliberately below
MIN_TOKEN_SCORE(50), so it never counts as a matched concept in a multi-word query. That is not a detail. I measured the alternative: dropping the floor to 45 movednested menufrom SideNav → List, andexplain why a field is requiredfrom Field → TextInput — in both cases a component whose guidance happens to mention the other word displacing the one that is the answer. Breadth is not relevance, the same reasonweakKeywordsare capped.With the floor left at 50, a 28-query sweep over realistic phrasings shows zero top-result changes and zero regressions, while every single-word gain above is kept.
Also
guidanceFromhandles the shape core actually ships —usage.bestPracticesentries are{guidance, description}objects, not strings.featuresis absent from every core doc today; it is read if present.search.doc.mjs) updated to describe the tier.Gates:
check:repogreen,lint:strict0 errors, search + build suites 32/32. (typecheck:strictfails identically onmainin an unbuilt worktree — it needspnpm buildfirst.)