ui-find
Skill2 starsChanged yesterdayMITView on GitHub
Find a component that already exists instead of writing a new one. Use when the user describes a UI need in words (\"a workflow timeline with running, failed and retrying states and expandable logs\"), asks what component to use, asks for alternatives to one, or asks whether something is already in the project. Searches the project first, then 500+ shadcn-spec registries, reads the candidates' real code and dependencies, ranks them against the project's stack and licence needs, and returns exact names and links.
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 45
Read the project's components.json too: its registries field names the registries this project has already accepted.
- Very specific: line 64
Read the output for what it is.
- Distinctive: line 114
Do not rank from a name and a one-line description.
- Distinctive: line 131
Look at the live preview on the source's own page as well.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Component find
A described component is not a component to invent. Most of what gets described already exists, with its states, its keyboard handling and its edge cases worked out by someone who shipped it.
1. Turn the words into requirements
Split the request before searching. Example request: "a modern workflow execution timeline with running, failed, retrying and completed states, expandable logs, and links to job details."
| Kind | From that request |
| What it is | A vertical list of ordered events with per-event detail |
| States it must carry | running, failed, retrying, completed, and the empty list |
| Behaviour | expand and collapse a row, keyboard reachable, a link out of each row |
| Data shape | an ordered array with status, timestamps, a log body, a job id |
| Density | the real case: how many steps does a long run have? |
| Visual | matches the product's existing list and status conventions |
Name the component category in the words other people use for it. The
request's words are often not the catalogue's. A "workflow execution
timeline" is catalogued as a timeline, a stepper, an activity feed or a log
viewer. Search all the plausible names. https://component.gallery settles
what a component is usually called and what it usually does.
2. Search the project first
A second copy of a component the product already has is a defect, not a choice.
rg -l --glob '!node_modules' -i 'timeline|stepper|activity' --glob '*.tsx' --glob '*.jsx' --glob '*.vue'Where the repository has a graft index, graft ask "where are list and status
components defined" is faster and cheaper than grepping.
Read the project's components.json too: its registries field names the
registries this project has already accepted.
3. Search the registries
node ../ui-design/scripts/find-components.js \
timeline stepper activity --limit 20Options that matter:
--curated-onlysearches only the read-and-licensed sources in sources.json;--registries <n>widens the long tail;--type anyincludes blocks, hooks and whole pages, not onlyregistry:ui;--jsonreturns a machine-readable result.
Read the output for what it is. The script fetches the public registry
directory at https://ui.shadcn.com/r/registries.json, which held 508
registries on 2026-10-27, each with a health status and an item count. It
then fetches each candidate registry's own catalogue. It scores items by
where the search terms appear: name first, then title, then description. It
caches for a day under ${XDG_CACHE_HOME:-~/.cache}/product-experience.
The score is a text match, not a judgement. It says a candidate is worth
reading. It says nothing about whether the component is any good, and the
directory's own ranking.score tracks availability and catalogue size, so a
registry of 12,000 icons outranks a carefully built set of 40 components. Never
present either number to the user as quality.
Other routes, when the script's coverage is not enough:
pnpm dlx shadcn@latest search @namespace --query <term>asks one registry directly, and reaches a registry that filters server-side.- The shadcn MCP server (
pnpm dlx shadcn@latest mcp init --client claude) exposes the same registries to natural-language requests. Use it when it is already configured; it is not needed for the script to work. - Registries with their own MCP server, such as
claude mcp add --transport http arc https://uiarc.dev/api/mcp. An added server is an installed dependency: ask before adding one. https://21st.dev/community/librariesindexes 167 libraries by name, which helps when the user names a library rather than a component. Its free plan allows two copies a day and its MCP retrieval starts at a paid plan, so search the free directory first.https://www.shadcn-labs.comis a hub, not a registry: its own/registry.jsonand/r/registry.jsonboth return 404. What it is good for is the surfaces the main directory does not cover, each a separate site with its own registry. Reach for one when the component is not a web page component at all:Need Site Terminal interface termcn.devEmail emailcn.runPDF pdfcn.devOpen Graph image ogimagecn.comVideo framecn.dev,snapcn.devShader and WebGPU shadercn.runRich text editor editorcn.vercel.appMCP and chat app interface mcpcn.devDiagram in MDX mdxcn.devConfirm the install command on the site itself. These were read as a directory listing, not installed.
4. Read the candidates
Do not rank from a name and a one-line description. For each serious candidate, read the real thing:
pnpm dlx shadcn@latest view @namespace/name # the files, deps and code
curl -s "https://<registry>/r/<name>.json" | jq '.dependencies, .files[0].content' | head -60What to look for in the code:
- the states it actually implements;
- whether status is carried by colour alone;
- keyboard and focus handling;
- whether it owns its own data fetching;
- how much of the project's stack it assumes;
- how many new dependencies it drags in.
Look at the live preview on the source's own page as well. A screenshot shows the dense case and the failure state that a description omits.
5. Rank by suitability
In this order. An earlier row beats a later one; a component that fails one of the first three is out whatever it looks like.
| # | What | How to judge it |
| 1 | Does it do the job | Every state and behaviour from step 1, or a clear seam to add the missing one |
| 2 | Licence and cost | Read at the source, in the repository's own LICENSE file. GitHub's sidebar label is a guess: it reports both DavidHDev/react-bits and DavidHDev/canvas-ui as NOASSERTION, and both are in fact MIT + Commons Clause, which permits use inside a product but forbids redistributing the components "alone, in a bundle, or as a ported version". That rules them out of a template or a starter kit you ship, and it is invisible from the label. An AGPL default, a paid tier or an unstated licence needs the user's decision before it ships |
| 3 | Stack fit | Same framework, styling system and component base. A Base UI component inside a Radix product is a second system |
| 4 | Design-system fit | Measure it against the project's DESIGN.md, where one exists: does it take the colour, type, radius and spacing tokens, or does it hard-code its own? A component that carries its own palette and radii spreads drift through every screen it lands on |
| 5 | Accessibility | Keyboard operable, named controls, status never by colour alone, focus visible |
| 6 | Responsive behaviour | Check at 375px, not only on the desktop preview |
| 7 | Customer usability | Does it suit the real density and the real labels, or only the demo's six tidy rows |
| 8 | Source quality | Readable code, a maintained repository, a stated version. Record the last push date where it is old |
| 9 | Install cost | New dependencies, peer versions, a build step, a font, a licence key |
| 10 | Maintenance | Code copied into the project is code the project now owns. Prefer fewer, larger, well-built pieces |
Then recommend one, with two to four lines on why. Name the runner-up, and what would make it the better choice. Where nothing fits, say what each candidate lacked and propose building it. Compose it from primitives the project already has wherever that is possible.
6. Install, integrate, verify
pnpm dlx shadcn@latest add @namespace/name --dry-run # see what it writes
pnpm dlx shadcn@latest add @namespace/nameInstalling a component writes files into the project and may add dependencies: confirm with the user before the first install from a source the project has not used before.
Then map it onto the project's tokens, render it with the real data and the
dense case, and walk it with ui-review. A component that was never
rendered in this product has not been evaluated.
Report
- The requirement, as split in step 1.
- What the project already had.
- The candidates read, with exact names and links: the source page, the registry item url, and the install command.
- The ranking, and the one recommended, with its licence as read.
- Which links were verified by fetching them, and which are inferred.
- What remains unverified: a preview not opened, a licence page not read, a licence not stated anywhere.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

