docs: rewrite the README for package consumers - #204
Merged
Conversation
The npm page is this file, and it was broken for anyone following it. The CSS section — the one section you must follow to get styling — told readers to import dist/styles/compat/daisy-primitives.css. That file is not in the published tarball, so the import throws. Meanwhile @pathscale/ui/index.css, which carries the base styles, both themes and the icon set, was never mentioned at all. The Motion section pointed at docs/motion.md, which does not exist in the repo and is not shipped either — `files` is ["dist"]. Rewritten around what a consumer needs: correct setup, theming, the 103 components by family, the conventions that hold across all of them, peer requirements, and subpath exports. Development and playground instructions move to CONTRIBUTING.md, where the audience actually is. Every import and URL was checked against the published 1.2.11 tarball rather than the working tree. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
These were on the package front page, where they are noise: `bun run build` and `bun run playground:dev` do nothing for someone who installed the package from npm. Also corrects the setup commands — `bun dev` / `bun build` were listed, but the scripts are `bun run dev` / `bun run build`. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
homepage pointed at the GitHub repo. js.software is the live component showcase and is the better landing page from npm. keywords were ["solid","solidjs"], which is most of the reason this package is hard to find on npm. Adds the terms people actually search: component-library, ui, design-system, tailwind, daisyui, headless-ui, accessible, typescript. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Contributor
|
🚀 Preview deployment is ready! You can view the preview at: https://pr-ui-preview-204.surge.sh |
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.
The README is the npm page, and it is currently broken for anyone who follows it.
The blocking bug
The CSS section — the one section you must follow to get any styling — says:
That file is not in the published package. I pulled the 1.2.11 tarball (930 files) and there is no
compat/directory at all. The export map does expose./dist/styles/*, so the specifier resolves to a missing file and throws. A first-time user hits an error before rendering anything.Meanwhile
@pathscale/ui/index.css— which@imports the base styles, both themes and the generated icon set — was never mentioned anywhere on the page. The most important line for a consumer was missing; the line that was there was wrong.The Motion section pointed at
docs/motion.md. That file does not exist in the repo, andfilesis["dist"]so no docs ship either. Dead pointer twice over.Both were already flagged as known-bad in
docs/ui-usage.md; the fix just never happened.What else was wrong
bun run build,bun run playground:dev— commands that do nothing for someone who installed from npm. Moved toCONTRIBUTING.md.data-theme, the token system — core features, invisible.keywords: ["solid","solidjs"]— most of why this is hard to find on npm.sideEffectsis set correctly, so tree-shaking works; nothing said so.What the page says now
Setup that works → theming → 103 components by family → the conventions that hold across all of them → requirements and peers → subpath exports → links out to
ui-usage.mdfor depth.homepagenow points at the showcase rather than the repo, and keywords cover what people search.Verification
Every import in the new README was resolved against the published 1.2.11 tarball, not the working tree — including
primitives/virtualizer, which I had initially written asprimitives/virtual-rowsbefore checking (it does not exist). All three URLs return 200. The component table is built from the shippeddist/components/directories, not from prose.Note
This does not change the npm page until the next publish. I have not published — that is irreversible and yours to run.
🤖 Generated with Claude Code