Strong foundation with great docs and clear structure, but testing and live examples need polish for real newcomers to move confidently.
last scored 2026-06-15
Readiness lenses
The same repo, two ways: how ready it is for an AI coding agent, and for a human newcomer. Switch lenses to see each one's score and checks.
How ready the repo is for an AI coding agent to read, build, and operate it.
27 of 34 checks passed across 6 categories.
Machine Orientation
5 checks passed2 problems found
- mediumAgent instructions file
AGENTS.md / CLAUDE.md is the direct, machine-read channel for entry points and conventions.
Fix: Add an AGENTS.md naming the entry points, the build/test commands, and the house conventions.
- lowArchitecture doc
An ARCHITECTURE doc hands an agent the module map instead of making it infer one.
Fix: Add an ARCHITECTURE.md describing the major components and how they fit.
- README present — An agent reconstructs what the repo is and how to work in it from the README first.
- Repository description set — The one-line description is the fastest orientation signal an agent reads.
- llms.txt present — An llms.txt is the emerging machine-orientation standard — a curated map for LLMs.
- Topics set — GitHub topics situate the repo's domain and stack for an agent at a glance.
- Contribution conventions are written down — A contributor guide is where an agent learns the branch, commit, and review conventions it must follow.
Reproducible Setup
5 checks passed1 problem found
- lowDev container
A .devcontainer gives an agent a one-command, fully-declared environment.
Fix: Add a .devcontainer so the toolchain is declared, not assumed.
- Lockfile committed — Without a lockfile two clones can resolve different dependency trees — the build isn't reproducible.
- Runtime / toolchain pinned — An unpinned runtime makes an agent guess the version a clean environment needs.
- Version pins are exact — A floating pin (a bare major, or a range) still drifts between installs.
- Env template present — A .env.example tells an agent which configuration keys it must supply to run.
- Container or dev-container — A Dockerfile / compose / devcontainer removes 'works on my machine' from setup.
Code Navigability
2 checks passed0 problems found
- Conventional source layout — A recognised src/ · lib/ · app/ layout lets an agent localise code without spelunking.
- TypeScript strict mode on — Strict typing gives an agent typed signatures to anchor an edit on, not guesses.
Verification Surface
6 checks passed1 problem found
- lowTask runner present
A Makefile / Taskfile / justfile gives an agent a single index of the project's commands.
Fix: Add a Makefile / Taskfile / justfile collecting the common commands.
- Tests present — Runnable tests are the ground truth an agent checks its own edits against.
- Test command defined — A `test` script is the documented, discoverable way to run the suite.
- Lint command defined — A linter an agent can run catches a class of mistakes before they ship.
- CI configured — Readable CI is the feedback loop an agent reads to know what 'green' means here.
- Typecheck command — A typecheck script lets an agent catch type errors before they ship.
- Build command — A documented build command is the discoverable way for an agent to produce artifacts.
Agent Safety
7 checks passed1 problem found
- lowCODEOWNERS present
CODEOWNERS marks the 'don't touch without review' zones an agent should respect.
Fix: Add a CODEOWNERS file marking the sensitive paths.
- No committed .env — A tracked real .env hands secrets to anything — including an agent — that reads the repo.
- No exposed secrets — Secret-shaped literals in tracked files are a live credential leak.
- .gitignore covers env files — An ignore rule for .env is what keeps the next careless commit from leaking secrets.
- Automated dependency updates — Dependabot / Renovate keeps dependencies patched without a human in the loop.
- .gitignore present — A .gitignore is the first guard against an agent committing secrets or build junk.
- Security policy — A SECURITY.md is where an autonomous security agent reads this repo's rules before acting on it.
- License makes the code reusable — Without a license an agent cannot safely copy, redistribute, or vendor any of this code.
Context Economy
2 checks passed2 problems found
- lowGenerated / vendored files marked
A .gitattributes linguist marker tells tools (and agents) what to skip.
Fix: Mark generated/vendored paths in .gitattributes (linguist-generated / linguist-vendored).
- lowNo oversized source file
A single file in the hundreds of KB blows past an agent's effective context window.
Fix: Split the largest files along their natural seams.
- Dependencies not vendored in — A committed node_modules / vendor tree drowns the real signal an agent needs.
- Build output not committed — Generated dist/ · build/ output is noise an agent has to read past.
How ready the repo is for a human newcomer to understand, set up, and contribute.
78 / 10020 of 25 checks passed across 6 categories.
First Impression
85README clearly states purpose and links to docs, but lacks a quick visual hook or minimal example inline.
The README immediately explains what shadcn/ui is—a customizable component library—and directs to docs and contributing guide. However, it misses a minimal copy-paste example showing what 'beautifully designed' actually looks like in code, forcing newcomers to click through to the documentation site before understanding the material value.
Getting Running
75Clear pnpm-based install, but no lockfile visible and test setup is complex with external server dependency.
The CONTRIBUTING.md gives straightforward steps: fork, clone, install with `pnpm install`, and run workspaces via `pnpm --filter`. However, there's no `pnpm-lock.yaml` in the snapshot to guarantee dependency reproducibility, and the test command (`pnpm test`) requires starting a dev server and awaiting `http://localhost:4000`, which is fragile for CI/local setup and not documented in the README.
Finding Your Way
80Well-organized monorepo with a clear structure table, but 9000+ files and weak per-module documentation.
CONTRIBUTING.md includes a helpful table mapping `apps/v4/app`, `apps/v4/components`, `apps/v4/registry`, and `packages/shadcn` to their purposes. However, the file tree shows 9000+ files with no per-package READMEs or architecture diagrams visible in the snapshot, making it hard for a newcomer to find entry points or understand how components flow from source to registry to CLI.
Path to Contribute
80CONTRIBUTING.md is detailed with commit conventions and workflow, but lacks issue templates, beginner labels, and PR guidance.
The guide covers fork → branch → install → dev workflow and commit conventions (though truncated mid-sentence), and mentions changesets and registry building. However, there are no visible issue/PR templates (GitHub templates exist in `.github/` but not described), no mention of beginner-friendly issue labels despite 2045 open issues, and no guidance on testing changes before submission.
Signs of Life
82Recent commits and established release pipeline, but 2045 open issues and no visible contributor activity in snapshot.
Last push was 2026-06-15, showing active maintenance, and the presence of changesets, GitHub Actions workflows, and a release pipeline indicates a mature release process. However, the snapshot shows 2045 open issues with no context on response times or PR merge rates, and no contributor stats visible, making it unclear how responsive the team is to newcomers or how inclusive the community feels.
Open Door
88MIT license clearly stated and SECURITY.md present, but no code of conduct visible in snapshot.
The README and package.json both declare MIT licensing, and the snapshot shows a SECURITY.md file indicating security practices are documented. However, no CODE_OF_CONDUCT.md is mentioned or visible in the file tree, so a newcomer has no explicit guidance on acceptable behavior or how to report misconduct in the community.
First Impression
3 checks passed0 problems found
- README present — The README is the first screen — with none, a newcomer has nothing to land on.
- Repository description set — The one-line description sets expectations before a newcomer even opens the README.
- Topics set — Topics situate the project's domain at a glance and help a newcomer find it.
Getting Running
5 checks passed1 problem found
- lowOne-click dev container
A .devcontainer lets a newcomer start in a cloud IDE with zero local setup.
Fix: Add a .devcontainer for a one-click, batteries-included environment.
- Lockfile committed — Without a lockfile a newcomer's install resolves differently and hits errors the docs don't mention.
- Prerequisite versions pinned — Unpinned prerequisites are the classic 'works on my machine' first-run failure.
- Env template present — A .env.example shows a newcomer exactly which settings they must fill in to run it.
- One-command environment — A Dockerfile / compose / devcontainer turns a fiddly setup into one command.
- Versions pinned exactly — A floating version still drifts — a newcomer can hit a break the maintainer never saw.
Finding Your Way
1 check passed2 problems found
- mediumArchitecture / overview doc
An overview hands a newcomer the map instead of making them reconstruct it.
Fix: Add an ARCHITECTURE.md (or a 'Project layout' README section) naming the key directories.
- lowNo oversized source file
A single thousand-line file is a wall a newcomer bounces off.
Fix: Split the largest files along their natural seams.
- Conventional source layout — A familiar src/ · lib/ · app/ layout lets a newcomer guess where things live.
Path to Contribute
5 checks passed1 problem found
- lowTask runner
A Makefile / Taskfile gives a contributor a single index of the project's commands.
Fix: Add a Makefile / Taskfile collecting the common dev commands.
- CONTRIBUTING guide — A CONTRIBUTING guide is the difference between a guessed and a guided first PR.
- Issue templates — Issue templates show a newcomer how to file something useful — and that contributions are welcome.
- Pull-request template — A PR template tells a first-time contributor what a good change includes.
- Test command defined — A documented test command lets a contributor check their change before opening a PR.
- Lint command — A linter lets a first-time contributor catch style issues before review.
Signs of Life
3 checks passed0 problems found
- Tests present — A test suite signals a project that's cared for, not abandoned.
- CI configured — Green CI on every change tells a newcomer the project is actively kept working.
- Automated dependency updates — Dependabot / Renovate activity is a visible heartbeat of ongoing maintenance.
Open Door
3 checks passed1 problem found
- lowCode of conduct
A code of conduct states the social ground rules that make it safe to step in.
Fix: Add a CODE_OF_CONDUCT.md (the Contributor Covenant is the de-facto standard).
- License present — With no license the project isn't legally reusable — the door is shut however friendly the README.
- License is a standard one — A non-standard or custom license is a legal question mark a newcomer won't resolve.
- Security policy — A SECURITY.md tells a newcomer how to report a problem responsibly.
Where the grip slips
- highGetting Running+12 pts if fixed
No lockfile visible; dependencies may not be reproducible
The snapshot shows package.json with pinned major versions (pnpm@10.33.4, unpinned patch versions for dependencies like @typescript-eslint/eslint-plugin@^8.49.0), but no pnpm-lock.yaml or yarn.lock is present. A newcomer running `pnpm install` risks installing incompatible patch versions, leading to 'works on my machine' failures and frustration when builds break.
Fix: Commit and include pnpm-lock.yaml in the repository snapshot. Ensure all dependencies use exact versions (remove ^ and ~) or document why semver ranges are intentional. Add a note in CONTRIBUTING.md: 'Run `pnpm install` to use the locked dependency tree.'
- highGetting Running+10 pts if fixed
Test command is fragile and undocumented; requires manual server setup
The root package.json defines `test` as `pnpm --filter=v4 registry:build && start-server-and-test v4:dev http://localhost:4000 test:dev`. This requires the v4 dev server to be running on port 4000, but there's no documentation explaining this dependency, how to verify the server is healthy, or what to do if the port is already in use. A newcomer will hit timeouts or connection errors without understanding why.
Fix: Add to CONTRIBUTING.md: 'To run tests locally: run `pnpm v4:dev` in one terminal, then `pnpm test:dev` in another. For CI, use `pnpm test` which starts the server automatically.' Create a troubleshooting section: 'If port 4000 is busy, kill the process or change PORT=5000 in your .env.'
- mediumFinding Your Way+9 pts if fixed
No per-package README or architecture diagram; monorepo is hard to navigate
The file tree shows 9000+ files across multiple apps and packages, but only one high-level structure table in CONTRIBUTING.md. There are no README.md files in `apps/v4/registry`, `packages/shadcn`, or major subdirectories. A newcomer looking to modify a component or understand the build pipeline must reverse-engineer it from code.
Fix: Create README.md files in: `packages/shadcn/`, `apps/v4/registry/`, and `apps/v4/components/`. Each should describe: purpose, how to add entries, expected file structure, and a quick example. Add a high-level architecture diagram to the root README (ASCII or link to a wiki page) showing data flow: source code → registry → v4 website → CLI output.
- mediumPath To Contribute+8 pts if fixed
2045 open issues with no guidance on picking a beginner task
The issue tracker has over 2000 open issues, but the snapshot shows no evidence of 'good-first-issue', 'beginner', or 'help-wanted' labels or filtered view. A newcomer wanting to contribute will be overwhelmed and unsure which issues are safe for them to tackle.
Fix: Add a section to CONTRIBUTING.md: 'Finding a Task: Look for issues labeled `good-first-issue` or `help-wanted`. These are scoped for newcomers.' Create and tag at least 10 such issues in the backlog. Link from README: 'Want to contribute? Start here: [good-first-issue](https://github.com/shadcn-ui/ui/labels/good-first-issue)'.
- mediumOpen Door+6 pts if fixed
No code of conduct; community rules and safety are unclear
The repository lacks a CODE_OF_CONDUCT.md file, so newcomers have no explicit guidance on expected behavior, how to report harassment, or how the maintainers handle conflicts. This raises barriers for marginalized contributors and shows a gap in community care.
Fix: Add a CODE_OF_CONDUCT.md file (e.g., using the Contributor Covenant) and link to it from README.md under 'Community' or 'Support'. Example: 'This project adheres to the Contributor Covenant Code of Conduct.'
- lowFirst Impression+4 pts if fixed
No minimal code example in README; newcomers must visit external site to see value
The README describes the library's purpose and links to docs, but does not show what using a component looks like in code. A visitor cannot immediately see the 'beautifully designed' claim validated without clicking through to ui.shadcn.com.
Fix: Add a 'Quick Start' section to README.md with a minimal example, e.g., 'import Button from '@/components/ui/button'; export default () => <Button>Click me</Button>'. Include a screenshot or animated GIF of the result.
- lowPath To Contribute+3 pts if fixed
Commit convention documentation is truncated; full guidelines are unclear
The CONTRIBUTING.md file's 'Commit Convention' section is cut off mid-sentence ('category(scope or module): message in your comm…'), so newcomers cannot see the complete convention or examples.
Fix: Complete the commit convention section in CONTRIBUTING.md with full examples, e.g., 'feat(button): add disabled state', 'fix(modal): close on escape key', 'docs(readme): update install instructions'. Reference the repo's commitlint config (.commitlintrc.json).
Show your score
[](https://latch.fyi/shadcn-ui/ui)Share this analysis
https://latch.fyi/shadcn-ui/uiFixed some issues? Re-analyze to measure your progress →
Copy the whole report
Grab the entire verdict in one go — a Markdown block for a README or an issue, plain text, or a prompt you can paste straight into an LLM.