docs: cut filler from README and docs site - #786
Draft
thebuilder wants to merge 3 commits into
Draft
Conversation
Rewrite the prose across the README, docs site, CONTRIBUTING, and SECURITY to say what the library does instead of how it feels. - README: drop the emoji and puffery from the feature list, replace the MDN-boilerplate option descriptions with one-sentence versions, and rewrite the testing and polyfill sections in plain language. - overview.mdx: replace the "Built for production React" marketing bullets with concrete mechanisms and numbers. - ssr.mdx: remove three copies of the same initialInView caveat and an orphan paragraph restating fallbackInView vs defaultFallbackInView. - configuration.mdx, core-apis.mdx, testing guides: split dense sentences, remove em dashes, drop "React surface" and other jargon. - CONTRIBUTING, SECURITY: sentence-case headings, trim the filler. Also fixes issues found along the way: broken indentation in the render-props sample, the typos "explictly", "intersecing" and "test files were you actively import", and the British "specialised" in an otherwise US-spelled doc set. Renaming the "Stop, pause, or choose a callback API" heading changed its anchor, so the link in core-apis.mdx is updated to match. Docs site builds clean.
|
|
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
commit: |
The landing page was in better shape than the markdown, so this is a smaller pass over the copy that was still doing marketing instead of explaining. - The demo feed teasers were the worst of it: "Design systems that travel", "A quiet note on shipping", "A scroll worth observing". Nine labels of evocative filler that would read identically in any other project. They are scroll filler, so number them. That also makes scroll position legible in a demo whose whole point is scrolling. - "Ideal for analytics, prefetching, or logging" becomes "Use it for". - The closing headline "Add a kilobyte. Ship the viewport." had a second half that does not mean anything. Now "Add a kilobyte. Know what is on screen.", which echoes the hero. - Page title dropped a duplicate "for React"; the product name already says it. - Site description traded "lightweight" for what the library actually does. - Em dashes out of the section-divider comments and CSS, per house style. Left the hero, feature grid, and section headings alone. They already make specific claims and have a voice.
vercel
Bot
temporarily deployed
to
Preview – react-intersection-observer-storybook
August 22, 2026 15:17
Inactive
The page gave impressions a full interactive section but never showed lazy loading, which is one of the main reasons people reach for this library. It appeared once, as a hyphenated word in the hero lead. Adds a section between the API scrollspy and the impression strip: - Six tiles that reserve their space, then mount their <img> only once the observer reports them within 200px of the viewport. No image element exists in the DOM before that, so the deferral is real rather than a CSS trick. - A counter showing how many have been requested, plus the useInView call that drives it. - A note pointing plain images at loading="lazy" instead, so the section does not oversell the observer for cases the platform already handles. The artwork is inline SVG data URIs. A tile that has not been reached costs nothing and the page pulls no extra files. Also leads with the use cases now that they have somewhere to point: - Hero lead opens with "Reveal on scroll, lazy-load images, track impressions, build infinite lists" before the technical framing. - README intro names scroll animations, lazy loading, impressions, and infinite scroll. - Site description swaps "lightweight" for those same use cases, which is also closer to what people search for. The index badge overlays the frame, so it needs to read against the empty placeholder and the loaded artwork both. It uses the theme foreground when deferred and white once loaded; a single colour only worked for one of them. Verified in the browser at 375, 768, and 1280, in both themes: deferred state holds 0/6 with no img elements, loading flips all six, the code panel does not overflow its column, and the page never scrolls horizontally.
thebuilder
changed the title
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.
Pass over every prose file in the repo to remove AI-writing tells and say what the library does rather than how it feels.
What changed
README.md got the most work:
useInViewanduseOnInViewit's easier than ever to monitor elements" is now "Hooks or component API -useInViewfor React state,useOnInViewfor callbacks,<InView>for render props and wrapper elements."rootrow was 45 words of MDN boilerplate. Now one sentence. Same treatment forskip,initialInView,fallbackInView,children, and the test-utils method table.🧪markers replaced with the word "Experimental".Docs site:
overview.mdx: "Built for production React" was four bullets of marketing ("Native and efficient", "Testable at the right layer"). Rewritten as "What you get" with actual mechanisms and numbers. Em dashes in the next-steps list gone.ssr.mdx: had real redundancy. "initialInViewcontrols the pre-observer render; it does not create an observer" appeared three separate times, plus an orphan paragraph restatingfallbackInViewvsdefaultFallbackInViewwithout backticks. One statement each now, 20 lines shorter.configuration.mdx: unpacked the colon-and-semicolon pileup in "Choose where to observe", dropped a duplicated "root must be an ancestor" sentence.core-apis.mdx: removed "React surface" (used twice).intersection-observer-v2.mdx: dropped a duplicated closing line about the mock and occlusion.CONTRIBUTING.md / SECURITY.md: "I'm thrilled that you're interested in contributing" is gone, headings to sentence case, "Please ensure that your changes are formatted" became "Format your changes".
Fixes found along the way
explictly,intersecing, "in test files were you actively import", "Ref's from useRef needs to have".specialisedin an otherwise US-spelled doc set (behavior,behaviourinconsistency).Reviewer notes
## Stop, pause, or choose a callback APIto## Stop or pause observationchanged its slug, so the referring link incore-apis.mdxis updated to match. I grepped for the other renamed headings (Hydration considerations,Choose a test boundary,Start simple) and nothing links to them.overview.mdx"What you get" bullets, which now make specific claims (shared observer instances, ~1.15kB gzipped) that should match reality.pnpm --filter docs buildpasses, 112 pages.